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

Class SurfaceArray

Instance Methods

Instance Properties


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


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


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.