Max2D

The Max2D module provides a set of commands for drawing 2D graphics.

Before using any of the Max2D commands, you must first go into 2D graphics mode using the Graphics command.

Max2D uses a system known as double buffering. This means that all drawing commands go to an offscreen, hidden backbuffer. To actually present the result of a sequence of drawing commands, you must Flip the backbuffer into view. Double buffering is an essential feature for achieving smooth, flicker free animation.

Drawing

Max2D provides support for the following drawing commands:

Drawing commandAction
ClsClears the viewport
PlotDraws a single pixel
DrawLineDraws a line
DrawRectDraws a rectangle
DrawOvalDraws an oval
DrawPolyDraws a polygon
DrawTextDraws some text
DrawImageDraws an image
DrawPixmapDraws a pixmap

Viewport, origin and handle

Drawing commands are clipped to a rectangular area known as the viewport. Only the area within the viewport is ever modified, and attempting to draw outside the viewport will result in the drawing command being clipped or chopped to the viewport. To set the viewport, use the SetViewport command.

Drawing commands are also offset by the current origin and handle. To set these properties, use the SetOrigin and SetHandle commands.

The current handle is an x,y coordinate subtracted from all drawing x,y coordinates before any rotation or scaling occurs. This allows you to provide a local 'center' for drawing. On the other hand, the current origin is an x,y coordinate added to all drawing x,y coordinates after any rotation or scaling.

Color, alpha and blend mode

Drawing commands are affected by the current color, alpha and blend mode. You can set these properties by using the SetColor, SetAlpha and SetBlend commands.

The current alpha value controls the transparency level when using the ALPHABLEND blend mode.

The current blend mode controls how pixels are combined with existing pixels in the back buffer and can be one of the following:

Blend modeEffect
SOLIDBLENDPixels overwrite existing backbuffer pixels
MASKBLENDPixels are drawn only if their alpha component is greater than .5
ALPHABLENDPixels are alpha blended with existing backbuffer pixels
LIGHTBLENDPixel colors are added to backbuffer pixel colors, giving a 'lighting' effect
SHADEBLENDPixel colors are multiplied with backbuffer pixel colors, giving a 'shading' effect

Rotation and scale

Drawing commands can be scaled and rotated using the SetScale and SetRotation commands. Rotation and scaling occur relative to the current handle.

Images

Images are pre-rendered chunks of graphics that can be efficiently drawn using a single DrawImage command. Images are typically stored in png, bmp or jpg format, and can be loaded using the LoadImage command.

Image drawing is also affected by color, alpha, blend, rotation and scale. The current color is multiplied with each pixel color before the image is drawn to the backbuffer, allowing you to tint images. To disable this effect, you should set the current color to white.

Images can also have a mask color. This is the color that represents transparency when an image is drawn using the MASKBLEND blend mode. To set the mask color, use the SetMaskColor command.

Images can be created by snapshotting regions of the back buffer using the GrabImage command.

Pixmaps

Pixmaps are used to manipulate images at a pixel level, see the Pixmap module for details.

LockImage allows for direct Image pixel access and requires a corresponding call to UnlockImage when you have have finished reading or modifying the pixels. The DrawPixmap and GrabPixmap commands allow you to move pixels to and from the current graphic display's backbuffer.

Collisions

Max2D features a multilayered pixel perfect collision system. The CollideRect and CollideImage commands provide a dual function allowing the drawing and hit testing of Rects and Images with any combination of 32 collision layers.

The current Scale, Rotation, Origin and Handle settings are taken into account so coordinates for the collision commands acurately match their drawing counterparts DrawRect and DrawImage.

ResetCollisions is used to clear any or all of the 32 collision layers provided.

Function reference

CountGraphicsModes()   Get number of available graphics modes

Returns: Number of available graphics modes

Use GetGraphicsMode to obtain information about an individual graphics mode


GetGraphicsMode( mode,width Var,height Var,depth Var,hertz Var )   Get information about a graphics mode

GetGraphicsMode returns information about a�pecific graphics mode. mode should be in the range 0 (inclusive) to the value returned by CountGraphicsModes (exclusive).


GraphicsModeExists( width,height,depth=0,hertz=0 )   Determine if a graphics mode exists

Returns: True if a matching graphics mode is found

A value of 0 for any of width, height, depth or hertz will cause that parameter to be ignored.


Graphics( width,height,depth=16,hertz=60 )   Set Graphics mode

Sets the current Max2D graphics mode. This command must be executed before any other Max2D commands. width and height specify the size, in pixels, of the graphics mode, depth specifies the bit depth and hertz specifies the refresh rate.

A depth value of 0 enables 'windowed mode'. This special mode is currently intended for debugging purposes only and should not be used for release builds. Improved support for windowed modes will be added shortly.

Example:

' graphics.bmx

' demonstrates a fullscreen graphics display

Graphics 640,480

DrawText "Press any key to exit",0,0
Flip

WaitKey
End

EndGraphics()   End Graphics mode

EndGraphics closes the current full screen 2D graphics display created with the Graphics command.


Flip()   Swap front and back buffers

Flip can only be used after a call to Graphics and must be executed to show the results of any drawing commands.

BlitzMax uses a double buffered graphics system where all drawing is done to a Back Buffer and what is shown on the screen is known as the Front Buffer. Flip causes the buffers to be swapped allowing for fast flicker free graphics animation.


Cls()   Clear back buffer

Clears the back buffer to the current SetClsColor. The default ClsColor is Black.

After a Flip command the contents of the back buffer is undefined, most often containing the contents of the last Front Buffer making a call to Cls() essential before calling any drawing commands in order to create the next frame of graphics for display.

Example:

' cls.bmx

' a spinning text message
' remove the call to cls to illustrate the
' need for clearing the screen every frame

Graphics 640,480
SetOrigin 320,240
While Not KeyHit(KEY_ESCAPE)
	Cls 
	SetRotation frame
	DrawText "Press Escape To Exit",0,0
	Flip
	frame:+1
Wend

SetClsColor( red,green,blue )   Set current Cls color

The red, green and blue parameters should be in the range of 0 to 255.


Plot( x#,y# )   Plot a pixel

Sets the color of a single pixel on the back buffer to the current drawing color defined with the SetColor command. Other commands that affect the operation of Plot include SetOrigin, SetViewPort, SetBlend and SetAlpha.

Example:

' plot.bmx

' plots a cosine graph
' scrolls along the graph using an incrementing frame variable 

Graphics 640,480

While Not KeyHit(KEY_ESCAPE)
	Cls
	For x=0 To 640
		theta=x+frame
		y=240-Cos(theta)*240
		Plot x,y
	Next
	frame=frame+1
	Flip
Wend

DrawRect( x#,y#,width#,height# )   Draw a rectangle

Sets the color of a rectangular area of pixels using the current drawing color defined with the SetColor command.

Other commands that affect the operation of DrawRect include SetHandle, SetScale, SetRotation, SetOrigin, SetViewPort, SetBlend and SetAlpha.

Example:

' drawrect.bmx

' draws a sequence of rectangles across the screen with
' increasing rotation and scale

' uses the frame variable to cycle through the values 0..9 for
' an animation effect between frames 

Graphics 640,480

SetBlend ALPHABLEND
SetAlpha 0.2

While Not KeyHit(KEY_ESCAPE)
	Cls
	DrawText "DrawRect Example",0,0
	For r=t To t+500 Step 10
		SetRotation r
		SetScale r/5,r/5
		DrawRect r,r,2,2
	Next
	t=t+1
	If t=10 t=0
	Flip	
Wend

DrawLine( x#,y#,x2#,y2# )   Draw a line

DrawLine draws a line from x,y to x2,y2 with the current drawing color.

BlitzMax commands that affect the drawing of lines include SetLineWidth, SetColor, SetHandle, SetScale, SetRotation, SetOrigin, SetViewPort, SetBlend and SetAlpha.

Example:

' drawline.bmx

' draws a cross hair at the mouse position using DrawLine

Graphics 640,480

HideMouse 

While Not KeyHit(KEY_ESCAPE)
	Cls
	x=MouseX()
	y=MouseY()
	DrawLine 320,240,x,y
	DrawLine x-2,y,x-10,y
	DrawLine x+2,y,x+10,y
	DrawLine x,y-2,x,y-10
	DrawLine x,y+2,x,y+10
	Flip
Wend

DrawOval( x#,y#,width#,height# )   Draw an oval

DrawOval draws an oval that fits in the rectangular area defined by x, y, width and height parameters.

BlitzMax commands that affect the drawing of ovals include SetColor, SetHandle, SetScale, SetRotation, SetOrigin, SetViewPort, SetBlend and SetAlpha.

Example:

' drawoval.bmx

' draws a pair of eyes using 4 DrawOval commands, 2 white, 2 blue
' positions the blue ovals so the eyes track the mouse

Graphics 640,480
While Not KeyHit(KEY_ESCAPE)
	Cls
	SetColor 255,255,255
	DrawOval 0,0,320,200
	DrawOval 320,0,320,200
	SetColor 0,0,255
	x=(MouseX()-320)/10
	y=(MouseY()-240)/10
	DrawOval 220-32+x,100+y,64,40
	DrawOval 420-32+x,100+y,64,40
	Flip
Wend

DrawPoly( xy#[] )   Draw a polygon

DrawPoly draws a polygon with corners defined by an array of x#,y# coordinate pairs.

BlitzMax commands that affect the drawing of polygons include SetColor, SetHandle, SetScale, SetRotation, SetOrigin, SetViewPort, SetBlend and SetAlpha.

Example:

' drawpoly.bmx

' draws a simple triangle using the
' DrawPoly command and an array of
' floats listed as 3 pairs of x,y
' coordinates

Local tri#[]=[0.0,0.0,100.0,100.0,0.0,100.0]

Graphics 640,480
While Not KeyHit(KEY_ESCAPE)
	Cls
	DrawPoly tri
	Flip
Wend

DrawText( t$,x#,y# )   Draw text

DrawText prints strings at position x,y of the graphics display using the current image font specified by the SetImageFont command.

Other commands that affect DrawText include SetColor, SetHandle, SetScale, SetRotation, SetOrigin, SetViewPort, SetBlend and SetAlpha.

Example:

' drawtext.bmx

' scrolls a large text string across the screen by decrementing the tickerx variable

Graphics 640,480

Local tickerx#=640

text$="Yo to all the Apple, Windows and Linux BlitzMax programmers in the house! "
text:+"Game development is the most fun, most advanced and definitely most cool "
text:+"software programming there is!"

While Not KeyHit(KEY_ESCAPE)
	Cls
	DrawText "Scrolling Text Demo",0,0
	DrawText text,tickerx#,400
	tickerx=tickerx-1
	If tickerx<-TextWidth(text) tickerx=640
	Flip	
Wend

End

DrawImage( image:TImage,x#,y#,frame=0 )   Draw an image to the back buffer

Drawing is affected by the current blend mode, color, scale and rotation.

If the blend mode is ALPHABLEND, then the image is also affected by the current alpha value.


DrawImageRect( image:TImage,x#,y#,w#,h#,frame=0 )   Draw an image to a rectangular area of the back buffer

Drawing is affected by the current blend mode, color, scale and rotation.

If the blend mode is ALPHABLEND, then the image is also affected by the current alpha value.


TileImage( image:TImage,x#=0#,y#=0#,frame=0 )   Draw an image in a tiled pattern

TileImage draws an image in a repeating, tiled pattern, filling the current viewport.


SetColor( red,green,blue )   Set current color

The SetColor command affects the color of Plot, DrawRect, DrawLine, DrawText and DrawPoly.

The red, green and blue parameters should be in the range of 0 to 255.


SetBlend( blend )   Set current blend mode

SetBlend controls how pixels are combined with existing pixels in the back buffer when drawing commands are used in BlitzMax.

blend should be one of:

Blend modeEffect
SOLIDBLENDPixels overwrite existing backbuffer pixels
MASKBLENDPixels are drawn only if their alpha component is greater than .5
ALPHABLENDPixels are alpha blended with existing backbuffer pixels
LIGHTBLENDPixel colors are added to backbuffer pixel colors, giving a 'lighting' effect
SHADEBLENDPixel colors are multiplied with backbuffer pixel colors, giving a 'shading' effect


SetAlpha( alpha# )   Set current alpha level

alpha should be in the range 0 to 1.

alpha controls the transparancy level when the ALPHABLEND blend mode is in effect. The range from 0.0 to 1.0 allows a range of transparancy from completely transparent to completely solid.


SetLineWidth( width# )   Sets pixel width of lines drawn with the DrawLine command

SetMaskColor( red,green,blue )   Set current mask color

The current mask color is used to build an alpha mask when images are loaded or modified. The red, green and blue parameters should be in the range of 0 to 255.


SetViewport( x,y,width,height )   Set drawing viewport

The current ViewPort defines an area within the back buffer that all drawing is clipped to. Any regions of a DrawCommand that fall outside the current ViewPort are not drawn.


SetOrigin( x#,y# )   Set drawing origin

The current Origin is an x,y coordinate added to all drawing x,y coordinates after any rotation or scaling.


SetHandle( x#,y# )   Set drawing handle

The drawing handle is a 2D offset added to the x,y location of all drawing commands. Unlike SetOrigin, the drawing handle is added before rotation and scale are applied providing a local origin.


SetRotation( rotation# )   Set current rotation

rotation is given in degrees and should be in the range 0 to 360.


SetScale( scale_x#,scale_y# )   Set current scale

scale_x and scale_y multiply the width and height of drawing commands where 0.5 will half the size of the drawing and 2.0 is equivalent to doubling the size.


SetTransform( rotation#=0,scale_x#=1,scale_y#=1 )   Set current rotation and scale

SetTransform is a shortcut for setting both the rotation and scale parameters in Max2D with a single function call.


ShowMouse()   Make the mouse pointer visible

HideMouse()   Make the mouse pointer invisible

LoadImageFont:TImageFont( url:Object,size,style=SMOOTHFONT )   Load an image font

Returns: An image font object


SetImageFont( font:TImageFont )   Set current image font

In order to DrawText in fonts other than the default system font use the SetImageFont command with a font handle returned by the LoadImageFont command.


TextWidth( text$ )   Get width of text

Returns: The width, in pixels, of text based on the current image font.

This command is useful for calculating horizontal alignment of text when using the DrawText command.


TextHeight( text$ )   Get height of text

Returns: The width, in pixels, of text based on the current image font.

This command is useful for calculating vertical alignment of text when using the DrawText command.


LoadImage:TImage( url:Object,flags=-1 )   Load an image

Returns: A new image object

url can be either a string or an existing pixmap.

flags can be 0, -1, or any combination of:

Flags valueEffect
FILTEREDIMAGEThe image is smoothed when scaled or rotated
DYNAMICIMAGEThe image can be modified using LockImage or GrabImage
MASKEDIMAGEThe image is masked with the current mask color


If flags is -1, the default auto image flags are used: See AutoImageFlags

To combine flags, use the | (Boolean OR) operator.

LoadAnimImage:TImage( url:Object,cell_width,cell_height,first_cell,cell_count,flags=FILTEREDIMAGE|MASKEDIMAGE )   Load a multi-frame image

Returns: An image object

LoadAnimImage extracts multiple image frames from a single, larger image. url can be either a string or an existing pixmap.

See LoadImage for valid flags values.


SetImageHandle( image:TImage,x#,y# )   Set an image's handle to an arbitrary point

AutoMidHandle( enable )   Enable or disable auto midhandle mode

When auto midhandle mode is enabled, all images are automatically 'midhandled' (see MidHandleImage) when they are created. If auto midhandle mode is disabled, images are handled by their top left corner.


AutoImageFlags( flags )   Set auto image flags

The auto image flags are used by LoadImage when no image flags are specified. See LoadImage for a full list of valid image flags.


MidHandleImage( image:TImage )   Set an image's handle to its center

ImageWidth( image:TImage )   Get width of an image

Returns: The width, in pixels, of image


ImageHeight( image:TImage )   Get height of an image

Returns: The height, in pixels, of image


CreateImage:TImage( width,height,frames=1,flags=-1 )   Create an empty image

Returns: A new image object

CreateImage creates an 'empty' image, which should be initialized using either GrabImage or LockImage before being drawn.

Please refer to LoadImage for valid flags values. The flags value is always combined with DYNAMICIMAGE.

Example:

' createimage.bmx

' creates a 256x1 image with a black to blue color gradient

Const ALPHABITS=$ff000000

Graphics 640,480

image=CreateImage(256,1)
map=LockImage(image)
For i=0 To 255
	WritePixel(map,i,0,ALPHABITS|i)
Next
UnlockImage(image)

DrawImageRect image,0,0,640,480
DrawText "Blue Color Gradient",0,0

Flip

WaitKey

LockImage:TPixmap( image:TImage,frame=0,read_lock=True,write_lock=True )   Lock an image for direct access

Returns: A pixmap representing the image contents

Locking an image allows you to directly access an image's pixels.

Only images created with the DYNAMICIMAGE flag can be locked.

Locked images must eventually be unlocked with UnlockImage before they can be drawn.


UnlockImage( image:TImage,frame=0 )   Unlock an image

Unlocks an image previously locked with LockImage.


GrabImage( image:TImage,x,y,frame=0 )   Grab an image from the back buffer

Copies pixels from the back buffer to an image frame.

Only images created with the DYNAMICIMAGE flag can be grabbed.

Example:

' grabimage.bmx

' draws a small graphic then uses grabimage to make an image

' as mask color and cls color both default to black a mask is 
' created for the grabbed where any pixels unset on the backbuffer
' become transparent in the grabbed image

Graphics 640,480

DrawLine 0,0,32,32
DrawLine 32,0,0,32
DrawOval 0,0,32,32

Local image=CreateImage(32,32)
GrabImage image,0,0

Cls
For Local i=1 To 100
	DrawImage image,Rnd(640),Rnd(480)
Next
Flip

WaitKey
 

DrawPixmap( pixmap:TPixmap,x,y )   Draw pixmap

GrabPixmap:TPixmap( x,y,width,height )   Grab pixmap

ResetCollisions(mask%=0)   Clears collision layers specified by the bits in mask, mask=0 for all layers.

CollideRect:Object[](x,y,w,h,collidemask%,writemask%,id:Object=Null)   Pixel accurate collision testing between image layers

The collidemask specifies any layers to test for collision with. The writemask specifies which if any collision layers the image is added to in it's currently transformed state. The id specifies an object to be returned to future CollideImage calls when collisions occur.


CollideImage:Object[](image:TImage,x,y,frame,collidemask%,writemask%,id:Object=Null)   Pixel accurate collision testing between transformed Images.

The collidemask specifies any layers to test for collision with. The writemask specifies which if any collision layers the image is added to in it's currently transformed state. The id specifies an object to be returned to future CollideImage calls when collisions occur.


GraphicsWidth()   Get width of Graphics mode

Returns: The width, in pixels, of the current Graphics mode


GraphicsHeight()   Get height of Graphics mode

Returns: The height, in pixels, of the current Graphics mode


GetGraphics( width Var,height Var,depth Var,hertz Var )   Get width, height, depth and hertz of current Graphics mode

Returns: The width and height in pixels, the depth in bits and the frequency in hertz of the current Graphics mode.


GetColor( red Var,green Var,blue Var )   Get red, green and blue component of current color

Returns: Red, green and blue values in the range 0..255


GetMaskColor( red Var,green Var,blue Var )   Get red, green and blue component of current mask color

Returns: Red, green and blue values in the range 0..255


GetAlpha#()   Get current alpha setting

Returns: the current alpha value in the range 0..1.0


GetBlend()   Get current blendmode setting

Returns: 0 (SOLIDBLEND), 1 (MASKBLEND) ,2 (ALPHABLEND), 3 (LIGHTBLEND) or 4 (SHADEBLEND).


GetOrigin( x# Var,y# Var )   Get current origin position

Returns: The horizontal and vertical position of the current origin


GetHandle( x# Var,y# Var )   Get current drawing handle

Returns: The horizontal and vertical position of the current drawing handle


GetViewport( x Var,y Var,width Var,height Var )   Get dimensions of current Viewport

Returns: The horizontal, vertical, width and height values of the current Viewport


GetRotation#()   Get current Max2D rotation setting

Returns: The rotation in degrees


GetScale( scale_x# Var,scale_y# Var )   Get current Max2D scale settings

Returns: The rotation in degrees


GetImageFont:TImageFont()   Get current font

Returns: The current font


Module Information

Modulebrl.max2d
Version 1.02
Author Mark Sibly, Simon Armstrong
License Blitz Shared Source Code
Copyright Blitz Research Ltd
Modserver BRL