iio Graphics Engine

The properties and functions relating to an objects rendering are not defined within the object itself.

Instead, these components are attached to the object's class when the iio Engine loads.

This design enables the iio Graphics Engine to attach itself to classes in non-iio libraries - like Box2D.

 

Primary Functions

Graphics functions are attached to iio and Box2D objects by default.

 

.draw( Canvas2DContext context )

Available to: all iio Objects, b2Joint, b2Body, b2Shape

- Draws this object with the given context.

//draw an object with our base canvas's context
obj.draw(io.context);
 

.clearSelf( Canvas2DContext context )

Available to: Shape

- Clears this object from the given context (draws a transparent shape in its place).

//clear an object from our canvas
obj.clearSelf(io.context);
 

Style Properties

Style properties are stored in a structure called styles.

This structure is attached to iio Objects by default, but must be 'prepped' when used with Box2D.

The properties that styles contains are always left undefined until you call their respective set function, or define them directly yourself.

 

styles.alpha :: Number

Available to: Obj, b2Joint, b2Shape

- The global alpha (opacity) property. The value is between [0,1].

- This property can be set with the setAlpha function.

//access the alpha property directly
obj.styles.alpha = 0;

//change the property with its set function
obj.setAlpha(.5);
 

styles.strokeStyle :: Color || Pattern || Gradient

Available to: Obj, b2Joint, b2Shape

- The style of this objects stroke. Refer to w3schools for more information about strokeStyle values.

- This property can be set with the setStrokeStyle function.

//access the strokeStyle property directly
obj.styles.strokeStyle = 'red';

//change the property with its set function
obj.setStrokeStyle('red');
 

styles.lineWidth :: Number

Available to: Obj, b2Joint, b2Shape

- The width of the stroke defined in strokeStyle.

- This property can be set with the setLineWidth or the setStrokeStyle functions.

//access the lineWidth property directly
obj.styles.lineWidth = 4;

//change the property with its set function
obj.setLineWidth(4);

//change the property with setStrokeStyle
obj.setStrokeStyle('red', 4);
 

styles.fillStyle :: Color || Pattern || Gradient

Available to: Shape, Text, b2Shape

- The style of this objects fill. Refer to w3schools for more information about fillStyle values.

- This property can be set with the setFillStyle function.

//access the fillStyle property directly
obj.styles.fillStyle = 'blue';

//change the property with its set function
obj.setFillStyle('blue');
 

styles.shadow :: Object

Available to: Obj, b2Joint, b2Shape

- An object that holds all of the styles relating to this objects shadow.

: shadow.shadowColor :: String

: shadow.shadowBlur :: Number

: shadow.shadowOffset :: Vec

- These properties all have a respective set function, or they can all be set at once by using the setShadow function.

//access the shadow properties directly
obj.styles.shadow.shadowColor = 'blue';
obj.styles.shadow.shadowOffset = new iio.Vec(10,10);

//set properties with their set functions
obj.setShadowBlur(4);
obj.setShadowColor('red');

//set all properties at once
obj.setShadow('rgb(150,150,150)',10,10,4);
 

styles.refLine :: Object

Available to: Circle, b2CircleShape

- This property activates the drawing of a reference line from the circle's center to its edge at 0 degrees.

- This properties can be set with the drawReferenceLine function.

//draw a rotation reference line on the circle
CircleInstance.refLine=true;
//is equivalent to
CircleInstance.drawReferenceLine();

//turn refLine off
CircleInstance.refLine=false;
//is equivalent to
CircleInstance.drawReferenceLine(false);
 

Style Functions

Style functions are attached to iio and Box2D objects by default.

 

.setAlpha( Number alpha )

- sets the global alpha (opacity) for this object.

- alpha values are in the range [0,1].

//make object transparent
obj.setAlpha(0);

//make object partially transparent
obj.setAlpha(.8);
 

.setStrokeStyle( Color||Pattern||Gradient style, Number width )

- sets the strokeStyle and optionally the lineWidth of this object. Refer to w3schools for more information about strokeStyle values.

//change an objects strokeStyle
obj.setStrokeStyle('red');

//change an objects strokeStyle and lineWidth
obj.setStrokeStyle('red', 4);
 

.setLineWidth( Number lineWidth )

Available to: Obj, b2Joint, b2Shape

- Sets the width this objects stroke.

//change an objects lineWidth
obj.setLineWidth(4);
 

.setFillStyle( Color||Pattern||Gradient style )

Available to: Shape, Text, b2Shape

- Sets the style of this objects fill. Refer to w3schools for more information about fillStyle values.

//change an objects fillStyle
obj.setFillStyle('blue');
 

.setShadow( String color, Vec offset, Number blur )

.setShadow( String color, Number: offsetX, offsetY, Number blur )

Available to: Obj, b2Joint, b2Shape

- Sets an objects shadow styles.

//set all shadow properties at once
obj.setShadow('rgb(150,150,150)',10,10,4);
 

.setShadowColor( String color )

Available to: Obj, b2Joint, b2Shape

- Sets the color of this objects shadow.

//set an objects shadow color
obj.setShadowColor('red');
 

.setShadowOffset( Vec offset )

.setShadowOffset( Number: offsetX, offsetY )

Available to: Obj, b2Joint, b2Shape

- Sets an objects shadow offset.

//set an objects shadow offset
obj.setShadowOffset(10,10);
 

.setShadowBlur( Number blur )

Available to: Obj, b2Joint, b2Shape

- Sets this objects shadow blur.

//set an objects shadow blur
obj.setShadowBlur(4);
 

.drawReferenceLine( Boolean turnOn )

Available to: Circle, b2CircleShape

- Activates or deactivates the drawing of a reference line from the circle's center to its edge at 0 degrees.

- turnOn is true by default.

//draw a rotation reference line on the circle
CircleInstance.drawReferenceLine();

//turn refLine off
CircleInstance.drawReferenceLine(false);
 

Effects Properties

These properties are undefined until you call an effects function or define them directly yourself.

 

fxFade :: Object

Available to: Obj, b2Shape, b2Joint

- an object with properties that control an automated fade in or fade out effect.

: fxFade.rate :: Number

: fxFade.alpha :: Number (target alpha value)

 

Effects Functions

Effects functions are attached to iio and Box2d objects by default.

 

.fade( Number: rate, alpha )

Available to: Obj, b2Shape, b2Joint

- starts a fade animation at the given rate. The fade animation will stop when the object's alpha (opacity) reaches the specified value.

 

.fadeIn( Number: rate, alpha )

Available to: Obj, b2Shape, b2Joint

- starts a fade in animation at the given rate. The fade animation will stop when the object's alpha (opacity) reaches the specified value.

 

.fadeOut( Number: rate, alpha )

Available to: Obj, b2Shape, b2Joint

- starts a fade out animation at the given rate. The fade animation will stop when the object's alpha (opacity) reaches the specified value.

 

Image Properties

These properties are undefined until you attach an image or define them directly yourself.

 

img :: Image

Available to: Shape, b2Shape

- A singular image that has been attached to this shape.

- The iio Graphics engine attaches additional properties to JS Images:

: img.pos :: Vec (offset relative to objects center)

: img.size :: Vec (drawing size of the image in pixels)

: img.scale :: Number (the drawing scale of the image)

: img.rotation :: Number (image rotation in radians)

- Note that these properties do not control the main objects properties - they are all directly applied to the image and relative to the parent shape's properties.

- These properties all have a respective set function.

 

Image Functions

Image functions are attached to iio and Box2D objects by default.

 

.addImage( Image img )

.addImage( String src, Function onloadCallback )

Available to: Shape, b2Shape

- Attaches a new image to this object.

//load the image
var img = new Image();
img.src = 'myImage.png';

//attach it when its done loading
img.onload = function(){
  shape.addImage(img);
}

//or..

//let iio load the image for us
obj.addImage('myImage.png', function(){
  //do something on load..
});
 

.createWithImage( Image img )

.createWithImage( String src, Function onloadCallback )

Available to: Rect, Circle

- Attaches the given image and sets the objects dimensions to match it.

//load the image
var img = new Image();
img.src = 'myImage.png';

//create a shape with the dimensions
//of our image
var box;
img.onload = function(){
  box = new iio.Rect().createWithImage(img);
}

//or..

//let iio load the image for us
box = new iio.Rect().createWithImage('myImage.png'
  ,function(){
    //do something on load..
   });
 

.flipImage( Boolean yes )

Available to: Shape, b2Shape

- flips the image along a vertical axis.

- default value is true the first time this function is called, then it acts as a toggle.

//flip image
obj.flipImage();
 

.setImgOffset( Vec offset )

.setImgOffset( Number offsetX, Number, offsetY )

Available to: Shape, b2Shape

- Sets the offset of the attached image.

//change an objects image offset
obj.setImgOffset(20,20);
 

.setImgSize( Vec size )

.setImgSize( Number width, Number, height )

Available to: Shape, b2Shape

- Sets the draw size of the attached image.

- Note that if 'native' is passed instead of a vector, the image will draw at its native size.

//change an objects image size
obj.setImgSize(50,50);

//set an objects image size to its
//native resolution
obj.setImgSize('native');
 

.setImgScale( Number scale )

Available to: Shape, b2Shape

- Sets the drawing scale of the attached image.

//make the attached image draw
//at half its true size
obj.setImgScale(0.5);
 

.setImgRotation( Number rotation )

Available to: Shape, b2Shape

- Sets the rotation of the attached image relative to the rotation of the shape.

- Rotation is measured in radians.

//change an objects image rotation
obj.setImgRotation(Math.PI/4);
 

.setPolyDraw( Boolean turnOn )

Available to: Circle, b2CircleShape

- Turning on polyDraw will make your circle shapes draw images as rectangles instead of as circles.

- You should use this if you have a circular image with a transparent background, as it will speed up the rendering process.

- turnOn is true by default.

//Draw image as a rectangle instead of
//as a circle
Circle.setPolyDraw();

//reverse the last code
Circle.setPolyDraw(false);
 

Anim Properties

These properties are undefined until you attach an anim or define them directly.

 

anims :: Array

Available to: Shape, b2Shape

- An array containing attached animations. An animation is an array of images or an Sprite.

- You can auto advance and restart an animation by using the nextAnimFrame function.

 

animKey :: Number

Available to: Shape, b2Shape

- the current animation index.

obj.anims[animKey][animFrame]
 

animFrame :: Number

Available to: Shape, b2Shape

- the current animation frame index.

obj.anims[animKey][animFrame]
 

Anim Functions

These functions are attached to iio Objects and Box2d Objects by default.

 

.addAnim( Array imgs )

.addAnim( Sprite sprite, String tag )

.addAnim( Array imgSrcs, Function onloadCallback )

Available to: Shape, b2Shape

- Attaches a new animation to this object.

//load the images
var imgs = [];
imgs[0] = new Image();
imgs[1] = new Image();
imgs[0].src = 'anim-frame-1.png';
imgs[1].src = 'anim-frame-2.png';

//attach an animation when the images
//are done loading
img.onload = function(){
  shape.addAnim(imgs);
}

//or..

//let iio load the images for us
obj.addAnim(['anim-frame-1.png'
            ,'anim-frame-2.png']
            ,function(){
               //do something on load..
             });
//or..

//get anim from a sprite in a sprite sheet
var marioSprites = new iio.SpriteMap('img/mariobros_cmp.png'
                                    ,16,32,function(){

  //code calls when image has loaded
  mario = new iio.Rect(100, io.canvas.height-groundY,16,32);

  mario.addAnim(marioSprites.getSprite(0,2),'walk');
  mario.addAnim(marioSprites.getSprite(4,4),'jump');
  mario.addAnim(marioSprites.getSprite(5,5),'duck');
});
 

.createWithAnim( Array imgs )

.createWithAnim( Array imgSrcs, Function onloadCallback, Number animFrame )

.createWithAnim( Sprite sprite, String tag, Number animFrame )

Available to: Rect, Circle

- Attaches the given animation and sets the objects dimensions to match it.

//load the images
var imgs = [];
imgs[0] = new Image();
imgs[1] = new Image();
imgs[0].src = 'anim-frame-1.png';
imgs[1].src = 'anim-frame-2.png';

//create a shape with the dimensions
//of our first animation image
var box;
img.onload = function(){
  box = new iio.Rect().createWithAnim(img);
}

//or..

//let iio load the image for us
box = new iio.Rect().createWithAnim(
                         ['anim-frame-1.png'
                         ,'anim-frame-2.png']
                         ,function(){
                          //do something on load..
                         });
//or...

//create with a sprite from a sprite sheet
var marioSprites = new iio.SpriteMap('img/mariobros_cmp.png'
                                     ,16,32,function(){
    //code calls when image has loaded
    mario = new iio.Rect(100, io.canvas.height-groundY)
       .createWithAnim(marioSprites.getSprite(6,6),'standing');
});
 

.setAnim( String tag, Number frame, Context ctx )

.setAnim( Number: key, frame, Context ctx )

.setAnim( String: tag, Context ctx )

.setAnim( Number: key, Context ctx )

Available to: Shape, b2Shape

- sets the animation properties of this object.

- a context must be specified if there is no global framerate and you want the object to redraw itself with the new image.

//set a new animation
obj.setAnim('standing');
 

.setAnimKey( Number frame )

Available to: Shape, b2Shape

- Changes the value of animKey to the given number.

//set a different animation frame
obj.setAnimKey(4);
 

.setAnimFrame( Number frame )

Available to: Shape, b2Shape

- Changes the value of animFrame to the given number.

//set a different animation frame
obj.setAnimFrame(4);
 

.nextAnimFrame()

Available to: Shape, b2Shape

- Advances the animation by one frame. If the animation frame reaches the end of the image sequence, this function will wrap it back to the start.

//advance an animation
obj.nextAnimFrame();
 

.playAnim( Number fps, AppManager io, Number canvasId )

.playAnim( String tag, Number fps, AppManager io, Number canvasId )

.playAnim( Number: tag, fps, AppManager io, Number canvasId )

Available to: Shape, b2Shape

- plays an attached animation at the given framerate.

- if no animation tag is specified, the animation at the current animKey is activated.

- you must pass a reference to your app's AppManager if you have not set a framerate on the canvas that the object is on.

//play a walk animation
mario.playAnim('walk',15,io);
 

.stopAnim( String tag, Context ctx )

.stopAnim( Number tag, Context ctx )

Available to: Shape, b2Shape

- stops the animation this object is currently playing.

- if a tag is specified, this function will stop the current animation and replace it with the first frame of the new one. Otherwise, it will keep the current animation but set its frame index to 0.

- a Context parametter is only necessary if there is no global framerate and the object will need to redraw itself.

//stop an animation
obj.stopAnim();

//stop an anim and replace with new anim
//..assume no global framerate
obj.stopAnim('standing',io.context);
 

SpriteMap

A class to help segment a sprite sheet into different Sprite animations.

 

Constructors

Functions used to instantiate new intances of the SpriteMap class.

iio.SpriteMap( Image src, Number sprW, sprH )

iio.SpriteMap( String src, Number sprW, sprH, Function onloadCallback, Anything callbackParam )

iio.SpriteMap( String src, Function onloadCallback, Anything callbackParam )

- creates a new SpriteMap object with the given sprite sheet source.

- sprW is short for sprite-width. Dito for sprH. Default values for both are 0.

//create a SpriteMap object, define 16x32 sprite cells, pass onload function
// - you can redefine sprite cell dimensions any time with setSpriteRes()
var marioSprites = new iio.SpriteMap('img/mariobros_cmp.png',16,32,function(){
  //code calls when image has loaded
  mario = new iio.Rect(100, io.canvas.height-groundY)
      .createWithAnim(marioSprites.getSprite(6,6),'standing');
});

Functions

 

.getSprite( Number: start, end )

.getSprite( Number row )

- returns a Sprite object with the specified frames.

- if start and end are specified, the returned Sprite will have frames corresponding to the specified range where the sprite grid is being read left to right.

- if row is specified, the returned sprite will have all frames in the indicated row.

//get a sprite from the SpriteMap
mario.addAnim(marioSprites.getSprite(0,2),'walk');
mario.addAnim(marioSprites.getSprite(4,4),'jump');
mario.addAnim(marioSprites.getSprite(5,5),'duck');
 

.setSpriteRes( Vector res )

.setSpriteRes( Number: x, y )

- sets this SpriteMap's sprite resolution to the given value.

//change this Map's sprite resolution
marioSprites.setSpriteRes(30,40);
 

Sprite

A class that indexes animation frames from a single SpriteMap.

 

Constructor

iio.Sprite( Image src )

- creates a new Sprite object that references the given sprite sheet source.

 

Properties

.frames :: Array

- an array containing sprite frame definitions .

: .frames[i].x : the x coordinate of the sprite frame at index i

: .frames[i].y : the y coordinate of the sprite frame

: .frames[i].w : the width of the sprite frame

: .frames[i].h : the height of the sprite frame

 

Functions

.addFrame( Number: x, y, w, h )

- adds a frame from this Sprite's source sheet with the specified dimensions, relative to the given position.