BlitMath

BlitMath

A class of static methods that aid in drawing a tileset onto a canvas. And aid 2D Array manipulation. One of the core Classes of the library.

Constructor

new BlitMath()

This constructor does nothing, all methods of this class are static.

Members

(static) _specs :BlitSpecs

Used in some calls to define the width and height of each individual tile draw. Default is 16x16. See BlitSpecs.

Type:
Properties
Name Type Description
_specs
See:

(static) functionAssignments :Array

An Array of tile values that is used by the dispatchFunctionAssignments method. dispatchFunctionAssignments will dispatch a PatternActionEvent for each value from this array that it finds in the 2D pattern passed to it.

Type:
  • Array

(static) tileDataHolder :Array

An Array of TileData Objects. You can use BlitMath.convertToTileDataHolder to create this Array.

Type:
  • Array

Methods

(static) addSpecificValuesToMultiArray(mda, values)

Adds values to the end of a 2D Array. The Array can have values of integers or [y,x] inner arrays.

Parameters:
Name Type Description
mda Array

2D Array of integers or arrays.
values Array

1D Array of values to add. The index of each value in this array matches the row index in the mda. Each value is pushed into the end of each repsective row of the mda.

(static) addValueToPosition(x, y, value, map, canvasObject, img, tw, th, clearWidth, clearHeight, tdh)

Adds a value to the position in the map and redraws the position using specificBlit.

Parameters:
Name Type Description
x Number

The x index of the position.
y Number

The y index of the position.
value Object

The [y,x] value to add.
map Array

A 2D Array of [y,x] values.
canvasObject CanvasObject

The CanvasObject to draw on/clear, if null no redraw happens.
img Img

The image to use.
tw Number

The width of each tile.
th Number

The height of each tile.
clearWidth number

will be same as tw.
clearHeight Number

will be same as th.
tdh Number | Boolean

If true map will not be used to create BlitMath.tileDataHolder, by default BlitMath.tileDataHolder is remade at the end of this method, using map.

(static) addValueToTileDataPosition(td, value, map, canvasObject, img, tw, th, clearWidth, clearHeight, tdh)

Adds a value to a TileData based tile position in the map and redraws the tile spot.

Parameters:
Name Type Description
td TileData

The TileData to remove from map. You can use TileData.make to create a TileData from your value.
value Array

The [y,x] value to add.
map Array

2D Array of [y,x] values.
canvasObject CanvasObject

The CanvasObject to draw on/clear.
img Img

The image to use.
tw Number

The width of each tile.
th Number

The height of each tile.
clearWidth number

will be same as tw.
clearHeight Number

will be same as th.
tdh Number | Boolean

If true map will not be used to create BlitMath.tileDataHolder, by default BlitMath.tileDataHolder is remade at the end of this method, using map.

(static) checkTileValueAt(x, y, patt, tileWidth, tileHeight, indexHolderPoint) → {Object}

Returns the tile value at the x y position in the patt.

Parameters:
Name Type Description
x Number

x position to check.
y Number

y position to check.
patt Array

2D Array to check.
tileWidth Number

the width of each tile.
tileHeight Number

the eight of each tile.
indexHolderPoint MoverPoint

An optional MoverPoint that would store the index of the result.
Returns:
Type
Object

(static) cloneMultiArray(mda) → {Array}

Clones a 2D Array and returns the new array.

Parameters:
Name Type Description
mda Array

2D Array to clone.
Returns:
Type
Array

(static) combinedPatternBlit(subject, source, pattern, toPointOffsetX, toPointOffsetY)

Draws pattern onto subject. Pattern is a 2D Array of bitwise combined numbers.

Parameters:
Name Type Description
subject CanvasObject

CanvasObject to draw on
source Img

The image to draw from.
pattern Array

A 2D Array of bitwise combined integers that defines each tile to draw.
toPointOffsetX Number

An optional horizontal offset of the whole result.
toPointOffsetY Number

An optional vertical offset of the whole result.

(static) convertInternalValues(arr, tileWidth, tileHeight, yIndex) → {Array}

Converts the internal values of a 1D Array into TileData Objects and returns a new array of TileData Objects. This method is used inside of the convertToTileDataHolder method.

Parameters:
Name Type Description
arr Array

a 1D Array
tileWidth Number

The width of each tile.
tileHeight Number

The height of each tile.
yIndex Number

The y index of each tile.
Returns:
Type
Array

(static) convertToTileDataHolder(patt, tileWidth, tileHeight)

Converts a 2D Array into BlitMath.tileDataHolder which holds each tile value as a TileData Object.

Parameters:
Name Type Description
patt Array

2D Array to convert into BlitMath.tileDataHolder
tileWidth Number

the width of each tile.
tileHeight Number

the eight of each tile.

(static) dispatchFunctionAssignments(eventDispatcher, handlerFunctionString, handlerObject, pattern, tileWidth, tileHeight)

Goes through the pattern and each time it finds a value from BlitMath.functionAssignments it dispatches a PatternActionEvent that gets handled by a method you define. That method would get a PatternActionEvent that contains information of the tile that caused the event.

Parameters:
Name Type Description
eventDispatcher EventDispatcher

EventDispatcher to use for the events.
handlerFunctionString String

String name of the handler function to call. The function should expect an event as a param.
handlerObject Object

Object that contains the handler function.
pattern Array

The 2D Array to iterate through and dispatch an event each time a value from functionAssignments is found.
tileWidth Number

The width of each tile.
tileHeight Number

The height of each tile.

(static) drawSquaresFromAreaOfPattern(subject, pattern, startC, endC, startR, endR, squareWidth, squareHeight, colorValues, toPointOffsetX, toPointOffsetY)

Draws squares from a 2D Array pattern of integers/arrays using just a defined area of the pattern, not the whole pattern.

Parameters:
Name Type Description
subject CanvasObject

The CanvasObject to draw the squares on.
pattern Array

The 2D Array of integers or arrays that defines the pattern to draw. when the inner values of the 2D Array are arrays this method uses just the first number in the inner array to get the number that will define the color of the tile. for example [7,5] 7 would be the number used.
startC Number

The column in the pattern to start from.
endC Number

The column in the pattern to end at.
startR Number

The row in the pattern to start from.
endR Number

The row in the pattern to end at.
squareWidth Number

The width of each square, default is 16.
squareHeight Number

The height of each square, default is 16.
colorValues Object

An Object containing the color each square should be, each value in the pattern would be associated with a color.
toPointOffsetX Number

Optional offset of the horizontal positon of the result.
toPointOffsetY Number

Optional offset of the vertical position of the result.

(static) drawSquaresFromPattern(subject, pattern, squareWidth, squareHeight, colorValues)

Draws squares from a 2D Array pattern of integers.

Parameters:
Name Type Description
subject CanvasObject

The CanvasObject to draw the squares on.
pattern Array

The 2D Array of integers that defines the pattern to draw.
squareWidth Number

The width of each square, default is 16.
squareHeight Number

The height of each square, default is 16.
colorValues Object

An Object containing the string html color value each square should be, each value in the pattern would be associated with a color, for example {1:"#6495ed",2:"#ff00ff",3:"#c8c8c8"}

(static) fasterCheckTileValueAt(x, y, pattLength, innerPattLength, tileWidth, tileHeight, indexHolderPoint)

Assings the index of the tile found in the 2D Array to indexHolderPoint. So to get the tile value you would then use pattern[indexHolderPoint.y][indexHolderPoint.x] This method does not return anything.

Parameters:
Name Type Description
x Number

x position to check.
y Number

y position to check.
pattLength Number

The length of the outer array of the 2D Array; patt.length.
innerPattLength Number

The length of the inner arrays in the 2D Array; patt[0].length.
tileWidth Number

the width of each tile.
tileHeight Number

the eight of each tile.
indexHolderPoint MoverPoint

An optional MoverPoint that would store the index of the result.

(static) getBasicPatternOf(thisTile, patt, tileWidth, tileHeight, leftToRight) → {Array}

Returns an Array of MoverPoints that make up the path of tiles.

Parameters:
Name Type Description
thisTile Number | Array

The value of the tile to make a path from.
patt Array

A 2D Array of tile values.
tileWidth Number

The width of each tile.
tileHeight Number

The height of each tile.
leftToRight Boolean

If false the search will begin from the right. Default is false.
Returns:
Type
Array

(static) getSpecs()

Returns BlitMath._specs

(static) getTileDataAt(x, y, patt, tileWidth, tileHeight) → {TileData}

Returns the tile found in the pattern as a TileData Object. If the pattern is not BlitMath.tileDataHolder, BlitMath.tileDataHolder will be created using the pattern.

Parameters:
Name Type Description
x Number

x position to check.
y Number

y position to check.
patt Array

2D Array of values.
tileWidth Number

the width of each tile.
tileHeight Number

the eight of each tile.
Returns:
Type
TileData

(static) isANonZeroTileAt(x, y, patt, tileWidth, tileHeight) → {Boolean}

Returns true if the tile value at the position does not contain any 0's. For values such as [0,1] this value returns false. Whereas isATileAt would return true.

Parameters:
Name Type Description
x Number

x position to check.
y Number

y position to check.
patt Array

2D Array to check.
tileWidth Number

The width of each tile.
tileHeight Number

The height of each tile.
Returns:
Type
Boolean

(static) isATileAt(x, y, patt, tileWidth, tileHeight) → {Boolean}

Returns true if the tile value at the position is not 0 or [0,0].

Parameters:
Name Type Description
x Number

A x position to check. The position not the index.
y number

A y position to check. The position not the index.
patt Array

2D Array to check.
tileWidth Number

The width of each tile.
tileHeight Number

The height of each tile.
Returns:
Type
Boolean

(static) patternAreaBlit(subject, source, pattern, startC, endC, startR, endR, indexXMethod, indexYMethod, toPointOffsetX, toPointOffsetY)

Draws from a 2D Array pattern using just a defined area of the pattern, not the whole pattern.

Parameters:
Name Type Description
subject CanvasObject

The CanvasObject to draw on.
source Img

The source image to draw from. The spritesheet/tileset.
pattern Array

The 2D Array that defines the pattern to draw. For this method any 2D Array containing any kind of values can be used. You can define how to calculate each tile index by passing methods to this method.
startC Number

The column in the pattern to start from.
endC Number

The column in the pattern to end at.
startR Number

The row in the pattern to start from.
endR Number

The row in the pattern to end at.
indexXMethod function

A method to call on each tile value that will return the x index of the tile in the pattern. If a x method is not defined the tile value will be used as the x index.
indexYMethod function

A method to call on each value that will return the y index of the tile in the pattern. If a y method is not defined, Blith._specs.blitIndex will be used for every y index.
toPointOffsetX Number

Optional offset of the horizontal positon of each square.
toPointOffsetY Number

Optional offset of the vertical position of each square.

(static) patternBlit(subject, source, pattern, indexXMethod, indexYMethod, toPointOffsetX, toPointOffsetY)

Draws the pattern onto the subject.

Parameters:
Name Type Description
subject CanvasObject

the CanvasObject to draw to
source Img

an html Image or loaded png/jpg file.
pattern Array 
 A 2D Array that, by default, holds Integers that denote the x index of each tile to draw from. 
	The y index to draw from, for this method, is by default defined by BlitMath._specs.blitIndex. 
     For example:  
     var pattern = [  
			[ 1, 1, 1 ], 
			[ 1, 0, 1 ], 
			[ 1, 1, 1 ] 
		]; 
  By default, to get the exact x position where in the source to draw from, this method multiplies BlitMath._specs.blitWidth *  each number in the patterns inner arrays.
  By default, each y position is determined by BlitMath._specs.blitHeight * BlitMath._specs.blitIndex.   BlitMath._specs is an instance of the BlitSpecs Class.

   By default BlitMath._specs has a blitWidth of 16 and blitHeight of 16 and blitIndex of 0.
   To change BlitMath._specs construct a new BlitSpecs instance, for example:    

   BlitMath._specs = new tabageos.BlitSpecs(16,16);
   BlitMath._specs.blitIndex = 0;
    
   patternBlit(subject,source,pattern);

   ---
 
  To change how the x index or y index is determined you can pass in a indexXMethod and/or indexYMethod.
 For example you could use decimal numbers to denote x and y index as follows:
  
  var pattern = [   
		[ 1.4, 1.4, 1.4],
		[ 1.4, 0.0, 1.4],
		[ 1.4, 1.4, 1.4]
  ];
  
  Then you need to define functions that would return the index values:

  var xInd = function(num) { return Math.floor(num); } //in this example: 1 or 0
  var yInd = function(num)  { return tabageos.splitNumberAtDecimal(num); }//in this example: 4 or 0

  and pass those functions during the patternBlit call:


  patternBlit(subject,source, pattern, xInd, yInd);

   Each x index is multiplied by BlitMath._specs.blitWidth to determine the x position in the source to draw from.
  Each y index is multipled by BlitMath._specs.blitHeight.

  The problem encountered when using decimals is that numbers with trailing zeros, for example: 1.10   would return 1 and 1, not 1 and 10.
  So for the location of drawing from a sprite sheet it is not ideal.

  ---

  Another option is to use bitwise operations to combine the values; 1 and 4 bitwsie combine as 65540.
  
  var pattern = [
      [tabageos.combineTwoNumbers(1,4), tabageos.combineTwoNumbers(1,4), tabageos.combineTwoNumbers(1,4)],
      [tabageos.combineTwoNumbers(1,4), tabageos.combineTwoNumbers(0,0),  tabageos.combineTwoNumbers(1,4)],
      [tabageos.combineTwoNumbers(1,4), tabageos.combineTwoNumbers(1,4), tabageos.combineTwoNumbers(1,4)]
  ];

   (you can use the combineTwoNumbers method as above, or you can use the ArrayMaker tool found on the tabageos site to make combined arrays for you)   

   var xInd = function(num) { return tabageos.getAFromCombined(num); }
   var yInd = function(num) { return tabageos.getBFromCombined(num); }
  
   patternBlit(subject, source, pattern, xInd, yInd);


 ---

  So the patternBlit method allows you to define how the x and y index is calibrated, or by default it expects just x indexes.

  If you have a special kind of way you like to set up your array values, patternBlit is what you would use, passing in functions that return x and y index based on your values.
 
   The specificaPatternBlit method takes only arrays that have [y,x]  values, for example:
   var pattern = [
     [ [4,1],[4,1],[4,1] ],
     [ [4,1],[0,0],[4,1] ],
     [ [4,1],[4,1],[4,1] ] 
   ];
   
   The combinedPatternBlit method takes only arrays that have bitwise combined xy values.
indexXMethod function

an optional method that would take a value in the array and return a x index, if not defined then the value itself is used as x index.
indexYMethod function

an optional method that would take a value in the array and return a y index, if not defined then BlitMath._specs.blitIndex is used as y index.
toPointOffsetX Number

an optional x offset to offset the x position of the whole drawing on the canvas.
toPointOffsetY Number

an optional y offset to offset the y position of the whole drawing on the canvas.

(static) removeTileData(td, map, canvasObject, img, tw, th, clearWidth, clearHeight, tdh)

Removes a tile from the map of specific [y,x] values using TileData and redraws the tile spot using specificBlit.

Parameters:
Name Type Description
td TileData

The TileData to remove from map. You can use TileData.make to create a TileData from your value.
map Array

2D Array of [y,x] values.
canvasObject CanvasObject

The CanvasObject to draw on/clear.
img Img

The image to use.
tw Number

The width of each tile.
th Number

The height of each tile.
clearWidth number

will be same as tw.
clearHeight Number

will be same as th.
tdh Number | Boolean

If true map will not be used to create BlitMath.tileDataHolder, by default BlitMath.tileDataHolder is remade at the end of this method, using map.

(static) replaceAllOfValueFromMultiArray(mda, value, rZero, rOne) → {Array}

Replaces value with rZero rOne. If the mda is a 2D Array of [y,x] arrays the matching values y is replaced with rZero and x with rOne. If the mda is a 2D Array of integers the matching value is replaced with rZero.

Parameters:
Name Type Description
mda Array

2D Array to clone.
value Number | Array

The value to replace.
rZero Number

Number to replace interger/first index in [y,x] value with.
rOne Number

Number to replace second index with.
Returns:
Type
Array

(static) replaceValuesFromMultiArray(mda, values, rZero, rOne) → {Array}

Replaces the values from the 2D Array. If the mda is a 2D Array of [y,x] arrays each matching values y is replaced with rZero and x with rOne. If the mda is a 2D Array of integers each matching value is replaced with rZero.

Parameters:
Name Type Description
mda Array

2D Array to clone.
values Array

1D Array of the values to replace.
rZero Number

Number to replace interger/first index in [y,x] value with.
rOne Number

Number to replace second index with.
Returns:
Type
Array

(static) resetTileDataHolder()

Resets BlitMath.tileDataHolder

(static) setSpecs(toThis)

Sets BlitMath._specs

Parameters:
Name Type Description
toThis BlitSpecs

(static) specificBlit(subject, source, pattern, tw, th, xIn, yIn)

Draws one tile from pattern onto subject using source. Using a specific style 2D Array of [y,x] values.

Parameters:
Name Type Description
subject CanvasObject

CanvasObject to draw on.
source Img

The image to draw from.
pattern Array

A 2D Array of [y,x] or [y,x,y,x] values.
tw Number

The width of each tile.
th Number

The height of each tile.
xIn number

The x index of the tile to draw.
yIn Number

The y index of the tile to draw.

(static) specificPatternAreaBlit(subject, source, pattern, startC, endC, startR, endR, toPointOffsetX, toPointOffsetY)

Draws from a 2D Array pattern of [y,x] values using just a defined area of the pattern, not the whole pattern.

Parameters:
Name Type Description
subject CanvasObject

The CanvasObject to draw on.
source Img

The source image to draw from. The spritesheet/tileset.
pattern Array

A 2D Array of [y,x] values that defines the pattern to draw.
startC Number

The column in the pattern to start from.
endC Number

The column in the pattern to end at.
startR Number

The row in the pattern to start from.
endR Number

The row in the pattern to end at.
toPointOffsetX Number

Optional offset of the horizontal positon of each square.
toPointOffsetY Number

Optional offset of the vertical position of each square.

(static) specificPatternBlit(subject, source, pattern, tw, th)

Draws pattern onto subject. Pattern is a 2D Array of [y,x] index values. The inner values can also be [y,x,y,x] in which case it draws two layers, the ending y,x first.

Parameters:
Name Type Description
subject CanvasObject

CanvasObject to draw on
source Img

The image to draw from.
pattern Array

A 2D Array of [y,x] values that defines each tile to draw. y,x are the index of the tile not the exact position.
tw Number

The width of each tile. BlitMath._specs.blitWidth is used. this param effects only how each tile is actually drawn on screen.
th Number

The height of each tile. BlitMath._specs.blitHeight is used. this param effects only how each tile is actually drawn on screen.

(static) valuesMatch(val1, val2) → {Boolean}

Compares the two values and returns true if they match. If each value is a Number it compares the numnbers. If each value is a Array it itterates through each array and if each value in the arrays matchs then it returns true.

Parameters:
Name Type Description
val1 Number | Array
val2 Number | Array
Returns:
Type
Boolean

(static) xySwitch(subject)

Assuming that subject is a 2D Array of [y,x] or [x,y] values, this method will switch the inner position of the numbers in each value, so [y,x] would become [x,y].

Parameters:
Name Type Description
subject CanvasObject

a 2D Array of [y,x] or [x,y] values.