Module gamejs/graphics

This module holds the important Surface class which is the general container for image data.

var surface = new gamejs.graphics.Surface([width, height]);

The functions to draw geometric lines like circles, lines, rectangles, etc. are also all in this module:

gamejs.graphics.line(surface, '#ff0000', centerPoint, radius);

Each Surface instance has methods to create a new rotated, flipped, scaled, etc. instance of itself:

// the original `surface` remains untouched by the
// filp operation. A new Surface instance
// is returned by `flip()`.
var horizontalFlippedSurface = surface.flip(true);

If you want to put images (png, jpg) on the screen, also see the gamejs.image module and gamejs.preload().

There are several ways to specify colors. Whenever the docs says "valid #RGB string" you can pass in any of the following formats: "#ff00ff", "rgb(255, 0, 255)" or "rgba(255, 0, 255, 1)".

See

gamejs/image

Functions

arc(surface, color, pos, startAngle,, stopAngle, radius, width)
bezierCurve(surface, color, startPos, endPos, ct1Pos, ct2Pos, width)
blitArray(surface, surfaceArray)
circle(surface, color, pos, radius, width)
line(surface, color, startPos, endPos, width)
lines(surface, color, closed, pointlist, width)
polygon(surface, color, pointlist, width)
quadraticCurve(surface, color, startPos, endPos, controlPos, width)
rect(surface, color, rect, width)

Class Surface

Instance Methods

blit(src, dst, area, compositionOperation)
clear(rect)
clone()
fill(CSS, a)
flip(flipHorizontal, flipVertical)
getAlpha()
getImageData()
getSize()
rotate(angle)
scale(dimensions)
setAlpha(alpha)

Class SurfaceArray

Instance Methods

get(x, y)
getSize()
set(x, y, rgba)

Instance Properties

surface

Surface (dimensions)

A Surface represents a bitmap image with a fixed width and height. The most important feature of a Surface is that they can be blitted onto each other.

Example

new gamejs.graphics.Surface([width, height]);
new gamejs.graphics.Surface(width, height);
new gamejs.graphics.Surface(rect);

Parameters

Array dimensions Array holding width and height

Surface.prototype.blit (src, dst, area, compositionOperation)

Blits another Surface on this Surface. The destination where to blit to can be given (or it defaults to the top left corner) as well as the Area from the Surface which should be blitted (e.g., for cutting out parts of a Surface).

Example

// blit flower in top left corner of display
displaySurface.blit(flowerSurface);

// position flower at 10/10 of display
displaySurface.blit(flowerSurface, [10, 10])

// ... `dest` can also be a rect whose topleft position is taken:
displaySurface.blit(flowerSurface, new gamejs.Rect([10, 10]);

// only blit half of the flower onto the display
var flowerRect = flowerSurface.rect;
flowerRect = new gamejs.Rect([0,0], [flowerRect.width/2, flowerRect.height/2])
displaySurface.blit(flowerSurface, [0,0], flowerRect);

Parameters

gamejs.graphics.Surface	src	The Surface which will be blitted onto this one
gamejs.Rect\|Array	dst	the Destination x, y position in this Surface. If a Rect is given, it's top and left values are taken. If this argument is not supplied the blit happens at [0,0].
gamesjs.Rect\|Array	area	the Area from the passed Surface which should be blitted onto this Surface.
Number	compositionOperation	how the source and target surfaces are composited together; one of: source-atop, source-in, source-out, source-over (default), destination-atop, destination-in, destination-out, destination-over, lighter, copy, xor; for an explanation of these values see: http://dev.w3.org/html5/2dcontext/#dom-context-2d-globalcompositeoperation

Returns

gamejs.Rect

Rect actually repainted FIXME actually return something?

Surface.prototype.clear (rect)

Clear the surface.

Parameters

rect

Surface.prototype.clone ()

Returns

gamejs.graphics.Surface

a clone of this surface

Surface.prototype.fill (CSS, a)

Fills the whole Surface with a color. Usefull for erasing a Surface.

Parameters

String	CSS	color string, e.g. '#0d120a' or '#0f0' or 'rgba(255, 0, 0, 0.5)'
gamejs.Rect	a	Rect of the area to fill (defauts to entire surface if not specified)

Surface.prototype.flip (flipHorizontal, flipVertical)

Flip a Surface either vertically, horizontally or both. This returns a new Surface (i.e: nondestructive).

Parameters

Boolean	flipHorizontal
Boolean	flipVertical

Returns

Surface

new, flipped surface

Surface.prototype.getAlpha ()

Returns

Number

current alpha value

Surface.prototype.getImageData ()

The data must be represented in left-to-right order, row by row top to bottom, starting with the top left, with each pixel's red, green, blue, and alpha components being given in that order for each pixel.

Returns

ImageData

an object holding the pixel image data {data, width, height}

See

http://dev.w3.org/html5/2dcontext/#canvaspixelarray

Surface.prototype.getSize ()

Returns

Number[]

the width and height of the Surface

Surface.prototype.rotate (angle)

Returns a new surface which holds this surface rotate by angle degrees. Unless rotating by 90 degree increments, the image will be padded larger to hold the new size.

Parameters

angel angle Clockwise angle by which to rotate

Returns

Surface

new, rotated surface

Surface.prototype.scale (dimensions)

Returns a new surface holding the scaled surface.

Parameters

Array dimensions new [width, height] of surface after scaling

Returns

Surface

new, scaled surface

Surface.prototype.setAlpha (alpha)

Set the alpha value for the whole Surface. When blitting the Surface on a destination, the pixels will be drawn slightly transparent.

Parameters

Number alpha value in range 0.0 - 1.0

Returns

Number

current alpha value

SurfaceArray (surfaceOrDimensions)

Fast pixel access. The SurfaceArray can be constructed with a surface whose values are then used to initialize the pixel array.

The surface passed as argument is not modified by the SurfaceArray.

If an array is used to construct SurfaceArray, the array must describe the dimensions of the SurfaceArray [width, height].

Example

// create array from display surface
  var srfArray = new SurfaceArray(display);
  // direct pixel access
  srfArray.set(50, 100, [255, 0, 0, 100]);
  console.log(srfArray.get(30, 50));
  // blit modified array back to display surface
  blitArray(display, srfArray);

Parameters

gamejs.graphics.Surface|Array surfaceOrDimensions

See

http://dev.w3.org/html5/2dcontext/#pixel-manipulation

SurfaceArray.prototype.get (x, y)

Get rgba value at position xy,

Parameters

Number	x
Number	y

Returns

Array

[red, green, blue, alpha]

SurfaceArray.prototype.getSize ()

SurfaceArray.prototype.set (x, y, rgba)

Set rgba value at position x, y.

For performance reasons this function has only one signature being Number, Number, Array4.

Parameters

Number	x	x position of pixel
Number	y	y position of pixel
Array	rgba	[red, green, blue, alpha] values [255, 255, 255, 255] (alpha, the last argument defaults to 255)

Throws

Error if x, y out of range

SurfaceArray.prototype.surface

a new gamejs.graphics.Surface on every access, representing the current state of the SurfaceArray.

arc (surface, color, pos, startAngle,, stopAngle, radius, width)

Parameters

gamejs.graphics.Surface	surface	the Surface to draw on
String	color	a valid #RGB String, #ff00cc
Array	pos	[x, y] position of the circle center
Number	startAngle,	both angles in radians
Number	stopAngle
Number	radius
Number	width	the width of line, if 0 or not given the arc is filled.

bezierCurve (surface, color, startPos, endPos, ct1Pos, ct2Pos, width)

Draw a bezier curve with two control points on the surface. The control point positions define the shape of the bezier curve.

Parameters

gamejs.graphics.Surface	surface	the Surface to draw on
String	color	valid #RGB string, e.g., "#ff0000"
Array	startPos	[x, y] the start position for the bezier curve
Array	endPos	[x, y] the end position for the bezier curve
Array	ct1Pos	[x, y] position of the first control point
Array	ct2Pos	[x, y] position of the second control point
Number	width	of the bezier curve, defaults to 1

blitArray (surface, surfaceArray)

Directly copy values from an array into a Surface.

This is faster than blitting the surface property on a SurfaceArray

The array must be the same dimensions as the Surface and will completely replace all pixel values.

Parameters

gamejs.graphics.Surface	surface
gamejs.graphics.Surfacearray.SurfaceArray	surfaceArray

circle (surface, color, pos, radius, width)

Draw a circle on Surface

Parameters

gamejs.graphics.Surface	surface	the Surface to draw on
String	color	a valid #RGB String, #ff00cc
Array	pos	[x, y] position of the circle center
Number	radius	of the circle
Number	width	width of the circle, if not given or 0 the circle is filled

line (surface, color, startPos, endPos, width)

Parameters

gamejs.graphics.Surface	surface	the Surface to draw on
String	color	valid #RGB string, e.g., "#ff0000"
Array	startPos	[x, y] position of line start
Array	endPos	[x, y] position of line end
Number	width	of the line, defaults to 1

lines (surface, color, closed, pointlist, width)

Draw connected lines. Use this instead of indiviudal line() calls for better performance

Parameters

gamejs.graphics.Surface	surface	the Surface to draw on
String	color	a valid #RGB string, "#ff0000"
Boolean	closed	if true the last and first point are connected
Array	pointlist	holding array [x,y] arrays of points
Number	width	width of the lines, defaults to 1

polygon (surface, color, pointlist, width)

Draw a polygon on the surface. The pointlist argument are the vertices for the polygon.

Parameters

gamejs.graphics.Surface	surface	the Surface to draw on
String	color	a valid #RGB String, #ff00cc
Array	pointlist	array of vertices [x, y] of the polygon
Number	width	the width of line, if 0 or not given the polygon is filled.

quadraticCurve (surface, color, startPos, endPos, controlPos, width)

Draw a quadratic curve with one control point on the surface. The control point position defines the shape of the quadratic curve.

Parameters

gamejs.graphics.Surface	surface	the Surface to draw on
String	color	valid #RGB string, e.g., "#ff0000"
Array	startPos	[x, y] the start position for the quadratic curve
Array	endPos	[x, y] the end position for the quadratic curve
Array	controlPos	[x, y] position of the control point
Number	width	of the quadratic curve, defaults to 1

rect (surface, color, rect, width)

Parameters

gamejs.graphics.Surface	surface	the Surface to draw on
String	color	a valid #RGB String, #ff00cc
gamejs.Rect	rect	the position and dimension attributes of this Rect will be used
Number	width	the width of line drawing the Rect, if 0 or not given the Rect is filled.