Cerberus X Documentation

Class DrawList

A drawlist contains drawing state and a sequence of 2d drawing operations. More...

Declarations

Extended By
Canvas
Please note that only documented classes are listed here, there might be undocumented classes that extend this one.
Properties
Alpha : Float () Return current alpha.
BlendMode : Int () Get blend mode.
Color : Float[] () Returns a 4 component float array containing current color and alpha.
DefaultMaterial : Material () Return the current default material.
Font : Font () Get font.
MatrixStackCapacity : Int () Get the maximum number of 2d matrices that can be pushed onto the matrix stack using PushMatrix.
Methods
AddShadowCaster : Void ( shadowCaster:ShadowCaster, tx:Float=0, ty:Float=0, rz:Float=0, sx:Float=1, sy:Float=1 ) Add a shadow caster to the drawlist.
DrawCircle : Void ( x:Float, y:Float, radius:Float, material:Material=Null ) Draw a circle at x, y with radius radius.
DrawEllipse : Void ( x:Float, y:Float, xRadius:Float, yRadius:Float, material:Material=Null ) Draw an ellipse at x, y with radii xRadius, yRadius.
DrawImage : Void ( image:Image, tx:Float, ty:Float, rz:Float ) Draw an image at tx,ty rotated by rz.
DrawImage : Void ( image:Image, tx:Float, ty:Float, rz:Float, sx:Float, sy:Float ) Draw an image at tx,ty rotated by rz and scaled by sx,sy.
DrawImage : Void ( image:Image, tx:Float=0, ty:Float=0 ) Draw an image at tx,ty.
DrawImage9P : Void ( image:Image, tx:Float, ty:Float, patchSize:Int, rz:Float, scaleX:Float, scaleY:Float ) Draws an 9-Patch image at coordinates tx, ty.
DrawIndexedPrimitives : Void ( order:Int, count:Int, vertices:Float[], texcoords:Float[], vertcols:Int[], indices:Int[], material:Material=Null ) Draw a batch of indexed primtives.
DrawIndexedPrimitives : Void ( order:Int, count:Int, vertices:Float[], texcoords:Float[], indices:Int[], material:Material=Null ) Draw a batch of indexed primtives.
DrawIndexedPrimitives : Void ( order:Int, count:Int, vertices:Float[], indices:Int[], material:Material=Null ) Draw a batch of indexed primtives.
DrawLine : Void ( x0:Float, y0:Float, x1:Float, y1:Float, material:Material=Null ) Draw a line from x0,y0 to x1,y1.
DrawOval : Void ( x:Float, y:Float, width:Float, height:Float, material:Material=Null ) Draw an oval in the given rectangle.
DrawPoint : Void ( x0:Float, y0:Float, material:Material=Null ) Draw a point at x0,y0.
DrawPrimitives : Void ( order:Int, count:Int, vertices:Float[], texcoords:Float[], vertcols:Int[], material:Material=Null ) Draw a batch of primtives.
DrawPrimitives : Void ( order:Int, count:Int, vertices:Float[], texcoords:Float[], material:Material=Null ) Draw a batch of primtives.
DrawPrimitives : Void ( order:Int, count:Int, vertices:Float[], material:Material=Null ) Draw a batch of primtives.
DrawQuad : Void ( x0:Float, y0:Float, x1:Float, y1:Float, x2:Float, y2:Float, x3:Float, y3:Float, material:Material=Null ) Draw a quad.
DrawRect : Void ( x:Float, y:Float, width:Float, height:Float, image:Image ) Draw a rect from x,y to x+width,y+height filled with image.
DrawRect : Void ( x:Float, y:Float, width:Float, height:Float, image:Image, sourceX:Int, sourceY:Int, sourceWidth:Int, sourceHeight:Int ) Draw a rect from x,y to x+width,y+height filled with the given subrect of image.
DrawRect : Void ( x:Float, y:Float, width:Float, height:Float, material:Material=Null ) Draw a rect from x,y to x+width,y+height.
DrawRect : Void ( x:Float, y:Float, image:Image, sourceX:Int, sourceY:Int, width:Int, height:Int ) Draw a rect at x,y filled with the given subrect of image.
DrawShadow : Void ( lightX:Float, lightY:Float, x0:Float, y0:Float, x1:Float, y1:Float ) Draw a shadow volume.
DrawShadows : Void ( lightX:Float, lightY:Float, drawList:DrawList ) Draw multiple shadow volumes.
DrawText : Void ( text:String, x:Float, y:Float, xhandle:Float=0, yhandle:Float=0 ) Draw text at x,y in the current font.
DrawTriangle : Void ( x0:Float, y0:Float, x1:Float, y1:Float, x2:Float, y2:Float, material:Material=Null ) Draw a triangle.
GetColor : Void ( color:Float[] ) Copy current color to color.
GetMatrix : Void ( matrix:Float[] ) Get current 2d matrix.
PopMatrix : Void () Pop the current 2d matrix from the 2d matrix stack.
PushMatrix : Void () Push the current 2d matrix on the 2d matrix stack.
Reset : Void () Removes all items from drawlist.
ResetMatrix : Void () Set the current 2d matrix to the identity matrix.
Rotate : Void ( rz:Float ) Rotate current 2d matrix.
RotateScale : Void ( rz:Float, sx:Float, sy:Float ) Rotate and scale (in that order) the current 2d matrix.
Scale : Void ( sx:Float, sy:Float ) Scale current 2d matrix.
SetAlpha : Void ( a:Float ) Set alpha only.
SetBlendMode : Void ( blendMode:Int ) Set blend mode.
SetColor : Void ( red:Float, green:Float, blue:Float ) Set color only.
SetColor : Void ( red:Float, green:Float, blue:Float, alpha:Float ) Set color and alpha.
SetDefaultMaterial : Int ( material:Material ) Set the default material used for drawing operations that use a null material.
SetFont : Void ( font:Font ) Set current font for use with DrawText.
SetMatrix : Void ( ix:Float, iy:Float, jx:Float, jy:Float, tx:Float, ty:Float ) Set the current 2d matrix to the given matrix.
SetMatrixStackCapacity : Void ( capacity:Int ) Set the maximum number of 2d matrices that can be pushed onto the matrix stack using PushMatrix.
Transform : Void ( ix:Float, iy:Float, jx:Float, jy:Float, tx:Float, ty:Float ) Multiply the current 2d matrix by the given matrix.
Translate : Void ( tx:Float, ty:Float ) Translate the current 2d matrix.
TranslateRotate : Void ( tx:Float, ty:Float, rz:Float ) Translate and rotate (in that order) the current 2d matrix.
TranslateRotateScale : Void ( tx:Float, ty:Float, rz:Float, sx:Float, sy:Float ) Translate, rotate and scale (in that order) the current 2d matrix.
Functions
PremultiplyArgb2Abgr : Int ( color:Int ) Returns a color that is premultiplied (rgb components multiplied by alpha) and has byte format reordered from argb (commonly used) to abgr (used internally).
PremultiplyArgb2Abgr : Void ( colors:Int[] ) Premultiplies colors (multiplies rgb components by alpha) and reorders the byte format from argb (commonly used) to abgr (used internally).

Detailed Discussion

A drawlist contains drawing state and a sequence of 2d drawing operations.

You add drawing operations to a drawlist using any of the Draw methods. When a drawing operation is added, the current drawing state is captured by the drawing operation. Further changes to the drawing state will not affect drawing operations already in the drawlist.

A Canvas extends DrawList, and can be used to draw directly to the app window or an image. A drawlist can also be rendered to a canvas using Canvas.RenderDrawList.

A drawlist's drawing state consists of:

Drawing stateDescription
Current colorSetColor
Current 2d matrixTranslate, Rotate, Scale, PushMatrix, PopMatrix
Current blend modeSetBlendMode
Current fontDrawText

Properties Documentation

Method Alpha : Float () Property

Return current alpha.

Method BlendMode : Int () Property

Get blend mode.

Method Color : Float[] () Property

Returns a 4 component float array containing current color and alpha.

Note: To avoid the overhead of an array copy, use GetColor instead.

Method Font : Font () Property

Get font.

Method MatrixStackCapacity : Int () Property

Get the maximum number of 2d matrices that can be pushed onto the matrix stack using PushMatrix.

See also: SetMatrixStackCapacity


Methods Documentation

Method DrawImage : Void ( image:Image, tx:Float, ty:Float, rz:Float )

Draw an image at tx,ty rotated by rz.

If the image has a shadow caster attached, the shadow caster will also be added to the drawlist.

Method DrawImage : Void ( image:Image, tx:Float, ty:Float, rz:Float, sx:Float, sy:Float )

Draw an image at tx,ty rotated by rz and scaled by sx,sy.

If the image has a shadow caster attached, the shadow caster will also be added to the drawlist.

Method DrawImage : Void ( image:Image, tx:Float=0, ty:Float=0 )

Draw an image at tx,ty.

If the image has a shadow caster attached, the shadow caster will also be added to the drawlist.

Method DrawImage9P : Void ( image:Image, tx:Float, ty:Float, patchSize:Int, rz:Float, scaleX:Float, scaleY:Float )

Draws an 9-Patch image at coordinates tx, ty.

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

Method DrawIndexedPrimitives : Void ( order:Int, count:Int, vertices:Float[], texcoords:Float[], vertcols:Int[], indices:Int[], material:Material=Null )

Draw a batch of indexed primtives.

order is the number of vertices for each primitive, eg: 1 for points, 2 for lines, 3 for triangles etc.

count is the number of primitives to draw.

The vertices array contains x,y vertex data.

The texcoords array contains s,t texture coordinate data.

The vertcols array contains premultiplied abgr color values, and must be at least count * order long.

The indices array contains vertex indices, and must be at least count * order long.

If material is null, the current default material is used.

See also: SetDefaultMaterial, PremultiplyArgb2Abgr

Method DrawIndexedPrimitives : Void ( order:Int, count:Int, vertices:Float[], texcoords:Float[], indices:Int[], material:Material=Null )

Draw a batch of indexed primtives.

order is the number of vertices for each primitive, eg: 1 for points, 2 for lines, 3 for triangles etc.

count is the number of primitives to draw.

The vertices array contains x,y vertex data.

The texcoords array contains s,t texture coordinate data.

The indices array contains vertex indices, and must be at least count * order long.

If material is null, the current default material is used.

See also: SetDefaultMaterial

Method DrawIndexedPrimitives : Void ( order:Int, count:Int, vertices:Float[], indices:Int[], material:Material=Null )

Draw a batch of indexed primtives.

order is the number of vertices for each primitive, eg: 1 for points, 2 for lines, 3 for triangles etc.

count is the number of primitives to draw.

The vertices array contains x,y vertex data.

The indices array contains vertex indices, and must be at least count * order long.

If material is null, the current default material is used.

See also: SetDefaultMaterial

Method DrawPrimitives : Void ( order:Int, count:Int, vertices:Float[], texcoords:Float[], vertcols:Int[], material:Material=Null )

Draw a batch of primtives.

order is the number of vertices for each primitive, eg: 1 for points, 2 for lines, 3 for triangles etc.

count is the number of primitives to draw.

The vertices array contains x,y vertex data, and must be at least count * order * 2 long.

The texcoords array contains s,t texture coordinate data, and must be at least count * order * 2 long.

The vertcols array contains premultiplied abgr color values, and must be at least count * order long.

If material is null, the current default material is used.

See also: SetDefaultMaterial, PremultiplyArgb2Abgr

Method DrawPrimitives : Void ( order:Int, count:Int, vertices:Float[], texcoords:Float[], material:Material=Null )

Draw a batch of primtives.

order is the number of vertices for each primitive, eg: 1 for points, 2 for lines, 3 for triangles etc.

count is the number of primitives to draw.

The vertices array contains x,y vertex data, and must be at least count * order * 2 long.

The texcoords array contains s,t texture coordinate data, and must be at least count * order * 2 long.

If material is null, the current default material is used.

See also: SetDefaultMaterial

Method DrawPrimitives : Void ( order:Int, count:Int, vertices:Float[], material:Material=Null )

Draw a batch of primtives.

order is the number of vertices for each primitive, eg: 1 for points, 2 for lines, 3 for triangles etc.

count is the number of primitives to draw.

The vertices array contains x,y vertex data, and must be at least count * order * 2 long.

If material is null, the current default material is used.

See also: SetDefaultMaterial

Method DrawRect : Void ( x:Float, y:Float, width:Float, height:Float, image:Image )

Draw a rect from x,y to x+width,y+height filled with image.

The image's handle is ignored.

Method DrawRect : Void ( x:Float, y:Float, width:Float, height:Float, image:Image, sourceX:Int, sourceY:Int, sourceWidth:Int, sourceHeight:Int )

Draw a rect from x,y to x+width,y+height filled with the given subrect of image.

The image's handle is ignored.

Method DrawRect : Void ( x:Float, y:Float, image:Image, sourceX:Int, sourceY:Int, width:Int, height:Int )

Draw a rect at x,y filled with the given subrect of image.

The image's handle is ignored.

Method GetColor : Void ( color:Float[] )

Copy current color to color.

color must have a length of at least 3. If the length of color is greater than 3, alpha is also copied.

Method GetMatrix : Void ( matrix:Float[] )

Get current 2d matrix.

matrix should be at least 6 elements in length.

Method PopMatrix : Void ()

Pop the current 2d matrix from the 2d matrix stack.

Method PushMatrix : Void ()

Push the current 2d matrix on the 2d matrix stack.

Method Reset : Void ()

Removes all items from drawlist.

Method ResetMatrix : Void ()

Set the current 2d matrix to the identity matrix. Same as SetMatrix( 1,0,0,1,0,0 ).

Method Rotate : Void ( rz:Float )

Rotate current 2d matrix.

Method RotateScale : Void ( rz:Float, sx:Float, sy:Float )

Rotate and scale (in that order) the current 2d matrix.

Method SetAlpha : Void ( a:Float )

Set alpha only. Doesn't affect color.

All color and alpha values should be in the range 0 to 1 inclusive.

Method SetBlendMode : Void ( blendMode:Int )

Set blend mode. The blendMode parameter should be one of:

ModeBlendFuncRender to back bufferRender to texture
BlendMode.Opaque-Opaque on back buffer
opaque - no blending
Opaque on texture
overwrites everything, even alpha
BlendMode.AlphaglBlendFunc( GL_ONE, GL_ONE_MINUS_SRC_ALPHA )Alpha on back buffer
alpha blending
Alpha on texture
mixes rgb
BlendMode.AdditiveglBlendFunc( GL_ONE, GL_ONE )Additive on back buffer
additive blending
Additive on texture
adds rgb
BlendMode.MultiplyglBlendFunc( GL_DST_COLOR, GL_ONE_MINUS_SRC_ALPHA )Multiply on back buffer
multiply blending
Multiply on texture
multiplies rgb
BlendMode.Multiply2glBlendFunc( GL_DST_COLOR, GL_ZERO )Multiply2 on back buffer
multiply blending ignoring alpha
Multiply2 on texture
multiplies rgb ingoring alpha, overwrites alpha
BlendMode.Alpha2glBlendFuncSeparate( GL_ZERO, GL_ONE, GL_ONE, GL_ZERO )Alpha2 on back buffer
no effect
Alpha2 on texture
no effect on rgb, overwrites alpha
BlendMode.Opaque2glBlendFunc( GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA )Opaque2 on back buffer
alpha blending for images that aren't premultiplied
Opaque2 on texture
mixes rgb and mixes alpha depending on alpha (yeah, weird)
BlendMode.AlphaStampglBlendFuncSeparate( GL_ZERO, GL_SRC_ALPHA, GL_ONE, GL_ZERO );
glBlendEquation(GL_FUNC_ADD);
AlphaStamp on back buffer
multiplies rgb with alpha
AlphaStamp on texture
multiplies rgb with alpha, overwrites alpha

Technically, the effects when rendering to back buffer are the same as when rendering to texture. But because the back buffer's alpha channel is ignored, the effects are perceived differently.

For the demonstration of the effects, these three images have been used (put on a checkered background to show transparency):

Image1: Image1 Image2: Image2 Image3: Image3

Image1 has no alpha, Image2 has alpha and is premultiplied (happens automatically in mojo2 when loading an image) Image3 has alpha but is not premultiplied. Image1 is rendered opaque, then Image2 and Image3 are rendered on top with indicated BlendMode. For the Render to back buffer, background is first cleared with a brownish color.

Method SetColor : Void ( red:Float, green:Float, blue:Float )

Set color only. Doesn't affect alpha.

All color and alpha values should be in the range 0 to 1 inclusive.

Method SetColor : Void ( red:Float, green:Float, blue:Float, alpha:Float )

Set color and alpha.

All color and alpha values should be in the range 0 to 1 inclusive.

Method SetDefaultMaterial : Int ( material:Material )

Set the default material used for drawing operations that use a null material.

See also: DefaultMaterial

Method SetFont : Void ( font:Font )

Set current font for use with DrawText.

If font is null, a default font is used.

Method SetMatrixStackCapacity : Void ( capacity:Int )

Set the maximum number of 2d matrices that can be pushed onto the matrix stack using PushMatrix.

See also: MatrixStackCapacity

Method Translate : Void ( tx:Float, ty:Float )

Translate the current 2d matrix.

Method TranslateRotate : Void ( tx:Float, ty:Float, rz:Float )

Translate and rotate (in that order) the current 2d matrix.

Method TranslateRotateScale : Void ( tx:Float, ty:Float, rz:Float, sx:Float, sy:Float )

Translate, rotate and scale (in that order) the current 2d matrix.


Functions Documentation

Function PremultiplyArgb2Abgr : Int ( color:Int )

Returns a color that is premultiplied (rgb components multiplied by alpha) and has byte format reordered from argb (commonly used) to abgr (used internally).

color = DrawList.PremultiplyArgb2Abgr( color )
Function PremultiplyArgb2Abgr : Void ( colors:Int[] )

Premultiplies colors (multiplies rgb components by alpha) and reorders the byte format from argb (commonly used) to abgr (used internally).

DrawList.PremultiplyArgb2Abgr( colors )