Module mojo.graphics

The graphics module contains various functions that allow you to draw 2D graphics on all supported monkey target platforms. More...

Classes:	Image
Constants:	AdditiveBlend : Int AlphaBlend : Int
Functions:	Cls : Int ( r:Float=0, g:Float=0, b:Float=0 ) CreateImage : Image ( width:Int, height:Int, frameCount:Int=1, flags:Int=image.defaultflags ) DeviceHeight : Int () DeviceWidth : Int () DrawCircle : Int ( x:Float, y:Float, r:Float ) DrawEllipse : Int ( x:Float, y:Float, xr:Float, yr:Float ) DrawImage : Int ( image:Image, x:Float, y:Float, frame:Int=0 ) DrawImage : Int ( image:Image, x:Float, y:Float, rotation:Float, scaleX:Float, scaleY:Float, frame:Int=0 ) DrawImageRect : Int ( image:Image, x:Float, y:Float, srcX:Int, srcY:Int, srcWidth:Int, srcHeight:Int, frame:Int=0 ) DrawImageRect : Int ( image:Image, x:Float, y:Float, srcX:Int, srcY:Int, srcWidth:Int, srcHeight:Int, rotation:Float, scaleX:Float, scaleY:Float, frame:Int=0 ) DrawLine : Int ( x1:Float, y1:Float, x2:Float, y2:Float ) DrawOval : Int ( x:Float, y:Float, w:Float, h:Float ) DrawPoint : Int ( x:Float, y:Float ) DrawPoly : Int ( verts:Float[] ) DrawRect : Int ( x:Float, y:Float, w:Float, h:Float ) DrawText : Int ( text:String, x:Float, y:Float, xalign:Float=0, yalign:Float=0 ) FontHeight : Float () GetAlpha : Float () GetBlend : Int () GetColor : Float[] () GetColor : Int ( color:Float[] ) GetFont : Image () GetMatrix : Float[] () GetMatrix : Int ( matrix:Float[] ) GetScissor : Float[] () GetScissor : Int ( scissor:Float[] ) LoadImage : Image ( path:String, frameCount:Int=1, flags:Int=image.defaultflags ) LoadImage : Image ( path:String, frameWidth:Int, frameHeight:Int, frameCount:Int, flags:Int=image.defaultflags ) PopMatrix : Int () PushMatrix : Int () ReadPixels : Void ( pixels:Int[], x:Int, y:Int, width:Int, height:Int, arrayOffset:Int=0, arrayPitch:Int=0 ) Rotate : Int ( angle:Float ) Scale : Int ( x:Float, y:Float ) SetAlpha : Int ( alpha:Float ) SetBlend : Int ( blend:Int ) SetColor : Int ( r:Float, g:Float, b:Float ) SetFont : Int ( font:Image, firstChar:Int=32 ) SetMatrix : Int ( m:Float[] ) SetMatrix : Int ( ix:Float, iy:Float, jx:Float, jy:Float, tx:Float, ty:Float ) SetScissor : Int ( x:Float, y:Float, width:Float, height:Float ) TextWidth : Float ( text:String ) Transform : Int ( m:Float[] ) Transform : Int ( ix:Float, iy:Float, jx:Float, jy:Float, tx:Float, ty:Float ) Translate : Int ( x:Float, y:Float )

Detailed Discussion

The graphics module contains various functions that allow you to draw 2D graphics on all supported monkey target platforms.

The module supports rendering of file based images, and a small set of simple primitives.

Transparency effects can be achieved using SetAlpha to set the global alpha level, and fullscreen rotation and scaling effects can be achieved using the various matrix commands such as Translate, Rotate and Scale.

The graphics module is state based, and commands that 'set' various states will remain in effect until a subsequent 'set' modifies the state.

Function Documentation

Function Cls : Int ( r:Float=0, g:Float=0, b:Float=0 )

Clears the graphics device to the specified color.

The current color, alpha and blend mode are ignored by Cls. However, the scissor rect is still used so only the area inside the scissor rect is cleared.

Function CreateImage : Image ( width:Int, height:Int, frameCount:Int=1, flags:Int=image.defaultflags )

Creates an empty image for use with WritePixels.

The contents of the image are initially undefined.

See also LoadImage

Function DeviceHeight : Int ()

***** Moved to mojo.app.DeviceHeight *****

Function DeviceWidth : Int ()

***** Moved to mojo.app.DeviceWidth *****

Function DrawCircle : Int ( x:Float, y:Float, r:Float )

Draws a circle of the given radius at coordinates x, y.

The circle is drawn using the current color, alpha, blend mode and matrix, and is clipped to the current scissor rectangle.

Function DrawEllipse : Int ( x:Float, y:Float, xr:Float, yr:Float )

Draws an ellipse of radii xRadius, yRadius at coordinates x, y.

The ellipse is drawn using the current color, alpha, blend mode and matrix, and is clipped to the current scissor rectangle.

See also DrawOval

Function DrawImage : Int ( image:Image, x:Float, y:Float, frame:Int=0 )

Draws an image at coordinates x, y, offset by the image's handle.

The image is drawn using the current color, alpha, blend mode and matrix, and is clipped to the current scissor rectangle.

See also LoadImage, DrawImageRect

Function DrawImage : Int ( image:Image, x:Float, y:Float, rotation:Float, scaleX:Float, scaleY:Float, frame:Int=0 )

Draws an image at coordinates x, y, offset by the image's handle.

The image is drawn using the current color, alpha, blend mode and matrix, and is clipped to the current scissor rectangle.

The rotation and scaleX, scaleY parameters provide a convenient way for you to 'locally' rotate and scale the image.

See also LoadImage, DrawImageRect

Function DrawImageRect : Int ( image:Image, x:Float, y:Float, srcX:Int, srcY:Int, srcWidth:Int, srcHeight:Int, frame:Int=0 )

Draws a sub-rectangle of an image at coordinates x, y, offset by the image's handle.

The image is drawn using the current color, alpha, blend mode and matrix, and is clipped to the current scissor rectangle.

See also LoadImage, DrawImage

Function DrawImageRect : Int ( image:Image, x:Float, y:Float, srcX:Int, srcY:Int, srcWidth:Int, srcHeight:Int, rotation:Float, scaleX:Float, scaleY:Float, frame:Int=0 )

Draws a sub-rectangle of an image at coordinates x, y, offset by the image's handle.

The image is drawn using the current color, alpha, blend mode and matrix, and is clipped to the current scissor rectangle.

The rotation and scaleX, scaleY parameters provide a convenient way for you to 'locally' rotate and scale the image.

See also LoadImage, DrawImage

Function DrawLine : Int ( x1:Float, y1:Float, x2:Float, y2:Float )

Draws a line from x1, y1 to x2, y2.

The line is drawn using the current color, alpha, blend mode and matrix, and is clipped to the current scissor rectangle.

Function DrawOval : Int ( x:Float, y:Float, w:Float, h:Float )

Draws an oval of size width, height at coordinates x, y.

The oval is drawn using the current color, alpha, blend mode and matrix, and is clipped to the current scissor rectangle.

See also DrawEllipse

Function DrawPoint : Int ( x:Float, y:Float )

Draws a point at the coordinates x, y.

The point is drawn using the current color, alpha, blend mode and matrix, and is clipped to the current scissor rectangle.

Function DrawPoly : Int ( verts:Float[] )

Draw a convex polygon using the provided vertices.

The polygon is drawn using the current color, alpha, blend mode and matrix, and is clipped to the current scissor rectangle.

If the polygon described by vertices is not convex, the results are undefined.

The vertices array must contain at least 3 x,y pairs.

Function DrawRect : Int ( x:Float, y:Float, w:Float, h:Float )

Draws a rectangle of size width, height at the coordinates x, y.

The rectangle is drawn using the current color, alpha, blend mode and matrix, and is clipped to the current scissor rectangle.

Function DrawText : Int ( text:String, x:Float, y:Float, xalign:Float=0, yalign:Float=0 )

Draws text at coordinates x, y in the current font.

The current font may be modified using SetFont. By default, an internal 7 x 13 white-on-black font is used.

xalign and yalign allow you to control the alignment of the text and should be in the range 0 for left/top alignment to 1 for right/bottom alignment. A value of .5 can be used for centering text horizontally or vertically.

The text is drawn using the current color, alpha, blend mode and matrix, and is clipped to the current scissor rectangle.

Note: The font functionality in mojo is very limited and intended mainly for debugging purposes.

Function FontHeight : Float ()

Returns the height of the current font.

Function GetAlpha : Float ()

Returns the current alpha level in the range 0 to 1 inclusive.

See also SetAlpha

Function GetBlend : Int ()

Returns the current blend mode. See SetBlend for possible return values.

See also SetBlend

Function GetColor : Float[] ()

Returns the current color as a 3 component float array containg the current color's red, green and blue components respectively.

See also SetColor

Function GetColor : Int ( color:Float[] )

Copies the current color to color.

The length of color must be at least 3.

See also SetColor

Function GetFont : Image ()

Returns the current font.

See also SetFont

Function GetMatrix : Float[] ()

Returns the current transformation matrix as an array of 6 floats.

See also SetMatrix

Function GetMatrix : Int ( matrix:Float[] )

Copies the current transformation matrix to matrix.

The length of matrix must be at least 6.

See also SetMatrix

Function GetScissor : Float[] ()

Returns the current scissor rectangle as a 4 component float array containg the scissor rectangle's x,y, width and height coordinates respectively.

See also SetScissor

Function GetScissor : Int ( scissor:Float[] )

Copies the current scissor rectangle to scissor.

The length of scissor must be at least 4.

See also SetScissor

Function LoadImage : Image ( path:String, frameCount:Int=1, flags:Int=image.defaultflags )

Loads an image from path.

The frames of a multi-frame image must be laid out in a single horizontal strip, in which case the width of the image is the width of image file divided by the number of frames, and the height of the image is the height of the image file.

The image must be a PNG or JPEG image format, and must have the three-letter file extension .png or .jpg (not .jpeg). PNGs with alpha transparency channels are supported.

Like all game data, the image file must be saved in your project's .data folder or one of its sub-folders.

If your images contain edge padding, you will need to use one of the padding flags such as XYPadding.

See DefaultFlags for a list of valid image flags.

Function LoadImage : Image ( path:String, frameWidth:Int, frameHeight:Int, frameCount:Int, flags:Int=image.defaultflags )

Loads an image from path.

The frames of a multi-frame image may occupy more than 1 row. In this case, frames should be laid out left-to-right, top-to-bottom.

The image must be a PNG or JPEG image format, and must have the three-letter file extension .png or .jpg (not .jpeg). PNGs with alpha transparency channels are supported.

Like all game data, the image file must be saved in your project's .data folder or one of its sub-folders.

If your images contain edge padding, you will need to use one of the padding flags such as XYPadding.

See DefaultFlags for a list of valid image flags.

Function PopMatrix : Int ()

Pops a matrix from the internal matrix stack and makes it the current matrix.

See also PushMatrix

Function PushMatrix : Int ()

Pushes the current matrix onto the internal matrix stack.

The matrix can be restored at a later time using PopMatrix.

See also PopMatrix

Function ReadPixels : Void ( pixels:Int[], x:Int, y:Int, width:Int, height:Int, arrayOffset:Int=0, arrayPitch:Int=0 )

Copies a rectangular section of pixels from the current render buffer into an int array.

The pixel data is stored in int-per-pixel ARGB format, with the alpha component stored in bits 24-31, the red component in bits 16-23, the green component in bits 8-15 and the blue component in bits 0-7.

The optional arrayOffset parameter allows you to specify an index into the array at which to start writing pixel values.

The optional arrayPitch parameter allows you to specify a 'pitch'. This is the number of array elements between successive rows in the array. If this is 0, then width is used as pitch, meaning pixel data is assumed to be 'tightly packed'.

Function Rotate : Int ( angle:Float )

Multiplies the current matrix by a matrix representing the specified rotation.

Function Scale : Int ( x:Float, y:Float )

Multiplies the current matrix by a matrix representing the specified scale.

Function SetAlpha : Int ( alpha:Float )

Sets the current global alpha level.

Alpha controls the 'mixing' that occurs when rendering. An alpha value of 1 results in completely opaque rendering, while 0 results in completely transparent rendering.

In the case of images which contain alpha, the alpha used for rendering is the product of each image pixel's alpha and the current global alpha.

Global alpha affects all drawing operations except for Cls.

See also GetAlpha

Function SetBlend : Int ( blend:Int )

Sets the current blending mode.

The current blending mode affects all drawing commands except for Cls.

The blend parameter can be one of the following:

Blend	Description
AlphaBlend	Rendering operations are alpha blended with existing graphics
AdditiveBlend	Rendering operations are additively blended with existing graphics

See also GetBlend

Function SetColor : Int ( r:Float, g:Float, b:Float )

Sets the current color.

The current color is used by all drawing operations except Cls.

Note: Drawing images in any color other than 255,255,255 on the HTML5 target will incur a major runtime overhead. For best results on the HTML5 target, either use colored images sparingly, or consider using 'pre-colored' images stored in multiple image files.

See also GetColor

Function SetFont : Int ( font:Image, firstChar:Int=32 )

Sets the font for use with DrawText.

The font parameter may be Null, in which case an internal 7x11 white-on-black font is used and the firstChar parameter is ignored.

Note: The font functionality in mojo is very limited and intended mainly for debugging purposes

See also GetFont

Function SetMatrix : Int ( m:Float[] )

Sets the current matrix.

See also GetMatrix

Function SetMatrix : Int ( ix:Float, iy:Float, jx:Float, jy:Float, tx:Float, ty:Float )

Sets the current matrix.

See also GetMatrix

Function SetScissor : Int ( x:Float, y:Float, width:Float, height:Float )

Sets the current scissor rectangle to the rectangle specified by x, y, width and height.

All drawing commands are 'clipped' to the current scissor rectangle. To disable clipping, set the scissor rectangle to 0,0,DeviceWidth,DeviceHeight.

The rectangle coordinates used with SetScissor are device coordinates, and are not affected by the current matrix.

See also GetScissor

Function TextWidth : Float ( text:String )

Returns the width of the given text.

Function Transform : Int ( m:Float[] )

Multiplies the current matrix by the specified matrix.

Function Transform : Int ( ix:Float, iy:Float, jx:Float, jy:Float, tx:Float, ty:Float )

Multiplies the current matrix by the specified matrix.

Function Translate : Int ( x:Float, y:Float )

Multiplies the current matrix by a matrix representing the specified translation.