Cerberus X Documentation

Module mojo.graphics

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

Declarations

Imported By
mojo , mojo.app
Please note that only documented modules are listed here, there might be undocumented modules that import this one.
Classes
Font The mojo Font class provides support for bitmap fonts.
Image An image is a rectangular area of pixels, loaded from an image file with LoadImage or grabbed from another image with GrabImage.
Constants
AdditiveBlend : Int
AlphaBlend : Int
Functions
Cls : Int ( col:Color ) Clears the graphics device to the specified Color.
Cls : Int ( rgb:Int ) Clears the graphics device to the specified hex color value.
Cls : Int ( r:Float=0, g:Float=0, b:Float=0 ) Clears the graphics device to the specified color.
CreateImage : Image ( width:Int, height:Int, frameCount:Int=1, flags:Int=Image.DefaultFlags ) Creates an empty image for use with Image.WritePixels.
DeviceHeight : Int () ***** Moved to mojo.app.DeviceHeight *****
DeviceWidth : Int () ***** Moved to mojo.app.DeviceWidth *****
DrawCircle : Int ( x:Float, y:Float, r:Float ) Draws a circle of the given radius at coordinates x, y.
DrawEllipse : Int ( x:Float, y:Float, xr:Float, yr:Float ) Draws an ellipse of radii xRadius, yRadius at coordinates x, y.
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.
DrawImage : Int ( image:Image, x:Float, y:Float, frame:Int=0 ) Draws an image at coordinates x, y, offset by the image's handle.
DrawImage9P : Int ( image:Image, x:Float, y:Float, patchSize:Int, rotation:Float, scaleX:Float, scaleY:Float, frame:Int=0 ) Draws an 9-Patch image at coordinates x, y, offset by the image's handle.
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.
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.
DrawLine : Int ( x1:Float, y1:Float, x2:Float, y2:Float ) Draws a line from x1, y1 to x2, y2.
DrawOval : Int ( x:Float, y:Float, w:Float, h:Float ) Draws an oval of size width, height at coordinates x, y.
DrawPoint : Int ( x:Float, y:Float ) Draws a point at the coordinates x, y.
DrawPoly : Int ( verts:Float[] ) Draw a convex polygon using the provided vertices.
DrawRect : Int ( x:Float, y:Float, w:Float, h:Float ) Draws a rectangle of size width, height at the coordinates x, y.
DrawText : Int ( text:String, x:Int, y:Int, xalign:Float=0, yalign:Float=0 ) Draws text at coordinates x, y in the current font.
DrawText : Void ( textLines:String[], x:Int, y:Int, xhandle:Float=0, yhandle:Float=0 ) Draws a multiline text beginning at coordinates x, y in the current font.
FontHeight : Float () Returns the height of the current font.
GetAlpha : Float () Returns the current alpha level in the range 0 to 1 inclusive.
GetBlend : Int () Returns the current blend mode.
GetColor : Float[] () Returns the current color as a 3 component float array containg the current color's red, green and blue components respectively.
GetColor : Int ( color:Float[] ) Copies the current color to color.
GetFont : Font () Returns the current font.
GetMatrix : Float[] () Returns the current transformation matrix as an array of 6 floats.
GetMatrix : Int ( matrix:Float[] ) Copies the current transformation matrix to matrix.
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.
GetScissor : Int ( scissor:Float[] ) Copies the current scissor rectangle to scissor.
LoadImage : Image ( path:String, frameWidth:Int, frameHeight:Int, frameCount:Int, flags:Int=Image.DefaultFlags ) Loads an image from path.
LoadImage : Image ( path:String, frameCount:Int=1, flags:Int=Image.DefaultFlags ) Loads an image from path.
PopMatrix : Int () Pops a matrix from the internal matrix stack and makes it the current matrix.
PushMatrix : Int () Pushes the current matrix onto the internal matrix stack.
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.
Rotate : Int ( angle:Float ) Multiplies the current matrix by a matrix representing the specified rotation.
Scale : Int ( x:Float, y:Float ) Multiplies the current matrix by a matrix representing the specified scale.
SetAlpha : Int ( alpha:Float ) Sets the current global alpha level.
SetBlend : Int ( blend:Int ) Sets the current blending mode.
SetColor : Int ( col:Color ) Sets the current color using a Color object.
SetColor : Int ( r:Float, g:Float, b:Float ) Sets the current color.
SetColor : Int ( rgb:Int ) Sets the current color using a hex color value.
SetFont : Void ( font:Font ) Sets the font for use with DrawText.
SetMatrix : Int ( ix:Float, iy:Float, jx:Float, jy:Float, tx:Float, ty:Float ) Sets the current matrix.
SetMatrix : Int ( m:Float[] ) Sets the current matrix.
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.
TextWidth : Float ( text:String ) Returns the width of the given text.
Transform : Int ( ix:Float, iy:Float, jx:Float, jy:Float, tx:Float, ty:Float ) Multiplies the current matrix by the specified matrix.
Transform : Int ( m:Float[] ) Multiplies the current matrix by the specified matrix.
Translate : Int ( x:Float, y:Float ) Multiplies the current matrix by a matrix representing the specified translation.

Detailed Discussion

The graphics module contains various functions that allow you to draw 2D graphics on all supported Cerberus 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.


Constants Documentation

Const AdditiveBlend : Int
Const AlphaBlend : Int

Functions Documentation

Function Cls : Int ( col:Color )

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 Cls : Int ( rgb:Int )

Clears the graphics device to the specified hex color value.

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 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 Image.WritePixels.

The contents of the image are initially undefined.

See also

LoadImage

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, 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, DrawImage9P, DrawImageRect

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, DrawImage9P, DrawImageRect

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

Draws an 9-Patch 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, scaleX and scaleY parameters provide a convenient way for you to 'locally' rotate and scale the image.

The scaling is done via the 9-Patch method. The patchSize determines the width and height of the top-height, bottom-height, left-width and right-width of the image. These are not scaled. The rest is.

See also

LoadImage, DrawImage, DrawImageRect

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, DrawImage9P

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, DrawImage9P

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:Int, y:Int, 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.

Function DrawText : Void ( textLines:String[], x:Int, y:Int, xhandle:Float=0, yhandle:Float=0 )

Draws a multiline text beginning 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.

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 : Font ()

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, 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.

See also

Resource paths, File formats, CreateImage, Image.DefaultFlags, Image.GrabImage

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.

See also

Resource paths, File formats, CreateImage, Image.DefaultFlags, Image.GrabImage

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:

BlendDescription
AlphaBlendRendering operations are alpha blended with existing graphics
AdditiveBlendRendering operations are additively blended with existing graphics
See also

GetBlend

Function SetColor : Int ( col:Color )

Sets the current color using a Color object.

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

Note: Drawing images in any color other than $FFFFFF 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.

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 SetColor : Int ( rgb:Int )

Sets the current color using a hex color value.

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

Note: Drawing images in any color other than $FFFFFF 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.

Function SetFont : Void ( font:Font )

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.

See also

Font.Load, GetFont

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 Translate : Int ( x:Float, y:Float )

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