# BlitzMax/Modules/Graphics/Max2D

The Max2D module provides a set of commands for drawing 2D graphics.
Before using any of the Max2D commands, you must first create a Max2D graphics object. The easiest way to do this is using the Graphics command.
By default, Max2D is double buffered which means you will have to use Flip once you have finished drawing each frame of graphics.

## Drawing

Max2D provides support for the following drawing commands:
| Drawing command | Action |
| Cls | Clears the viewport |
| Plot | Draws a single pixel |
| DrawLine | Draws a line |
| DrawRect | Draws a rectangle |
| DrawOval | Draws an oval |
| DrawPoly | Draws a polygon |
| DrawText | Draws some text |
| DrawImage | Draws an image |
| DrawPixmap | Draws 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 mode | Effect |
| SOLIDBLEND | Pixels overwrite existing backbuffer pixels |
| MASKBLEND | Pixels are drawn only if their alpha component is greater than .5 |
| ALPHABLEND | Pixels are alpha blended with existing backbuffer pixels |
| LIGHTBLEND | Pixel colors are added to backbuffer pixel colors, giving a 'lighting' effect |
| SHADEBLEND | Pixel 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 pixmaps module for details.
LockImage allows for direct Image pixel access and requires a corresponding call to UnlockImage when you 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 accurately match their drawing counterparts DrawRect and DrawImage. ResetCollisions is used to clear any or all of the 32 collision layers provided.

# Functions
## Cls

Function Cls
Description: Clear graphics buffer
Information: Clears the graphics buffer to the current cls color as determined by SetClsColor.
Example:

## SetClsColor

Function SetClsColor( red,green,blue )
Description: Set current Cls color
Information: The red, green and blue parameters should be in the range of 0 to 255.
The default cls color is black.

## GetClsColor

Function GetClsColor( red Var,green Var,blue Var )
Description: Get red, green and blue component of current cls color.
Returns: Red, green and blue values in the range 0..255 in the variables supplied.

## Plot

Function Plot( x#,y# )
Description: Plot a pixel
Information: 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:

## DrawRect

Function DrawRect( x#,y#,width#,height# )
Description: Draw a rectangle
Information: 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:

## DrawLine

Function DrawLine( x#,y#,x2#,y2#,draw_last_pixel=True )
Description: Draw a line
Information: 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. The optional draw_last_pixel parameter can be used to control whether the last pixel of the line is drawn or not. Not drawing the last pixel can be useful if you are using certain blending modes.
Example:

## DrawOval

Function DrawOval( x#,y#,width#,height# )
Description: Draw an oval
Information: 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:

## DrawPoly

Function DrawPoly( xy# )
Description: Draw a polygon
Information: 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:

## DrawText

Function DrawText( t$,x#,y# )
Description: Draw text
Information: 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.
It is recommended that the blend mode be set to ALPHABLEND using the SetBlend command for non jagged antialiased text. Text that will be drawn at a smaller size using the SetScale command should use fonts loaded with the SMOOTHFONT style to benefit from mip-mapped filtering, see LoadImageFont for more information.
Example:

## DrawImage

Function DrawImage( image:TImage,x#,y#,frame=0 )
Description: Draw an image to the back buffer
Information: Drawing is affected by the current blend mode, color, scale and rotation.
If the blend mode is ALPHABLEND the image is affected by the current alpha value and images with alpha channels are blended correctly with the background.

## DrawImageRect

Function DrawImageRect( image:TImage,x#,y#,w#,h#,frame=0 )
Description: Draw an image to a rectangular area of the back buffer
Information: 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.

## DrawSubImageRect

Function DrawSubImageRect( image:TImage,x#,y#,w#,h#,sx#,sy#,sw#,sh#,hx#=0,hy#=0,frame=0 )
Description: Draw a sub rectangle of an image to a rectangular area of the back buffer
Information: x, y, w and h specify the destination rectangle to draw to. sx, sy, sw and sh specify the source rectangle within the image to draw from.
hx and hy specify a handle offset within the source rectangle.
frame is the image frame to draw.
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

Function TileImage( image:TImage,x#=0#,y#=0#,frame=0 )
Description: Draw an image in a tiled pattern
Information: TileImage draws an image in a repeating, tiled pattern, filling the current viewport.

## SetColor

Function SetColor( red,green,blue )
Description: Set current color
Information: The SetColor command affects the color of Plot, DrawRect, DrawLine, DrawText, DrawImage and DrawPoly.
The red, green and blue parameters should be in the range of 0 to 255.

## GetColor

Function GetColor( red Var,green Var,blue Var )
Description: Get red, green and blue component of current color.
Returns: Red, green and blue values in the range 0..255 in the variables supplied.

## SetBlend

Function SetBlend( blend )
Description: Set current blend mode
Information: 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 mode | Effect |
| MASKBLEND | Pixels are drawn only if their alpha component is greater than .5 |
| SOLIDBLEND | Pixels overwrite existing backbuffer pixels |
| ALPHABLEND | Pixels are alpha blended with existing backbuffer pixels |
| LIGHTBLEND | Pixel colors are added to backbuffer pixel colors, giving a 'lighting' effect |
| SHADEBLEND | Pixel colors are multiplied with backbuffer pixel colors, giving a 'shading' effect |

## GetBlend

Function GetBlend
Description: Get current blend mode
Returns: The current blend mode.
Information: See SetBlend for possible return values.

## SetAlpha

Function SetAlpha( alpha# )
Description: Set current alpha level
Information: alpha should be in the range 0 to 1.
alpha controls the transparency level when the ALPHABLEND blend mode is in effect. The range from 0.0 to 1.0 allows a range of transparency from completely transparent to completely solid.

## GetAlpha

Function GetAlpha#
Description: Get current alpha setting.
Returns: the current alpha value in the range 0..1.0

## SetLineWidth

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

## GetLineWidth

Function GetLineWidth#
Description: Get line width
Returns: Current line width, in pixels

## SetMaskColor

Function SetMaskColor( red,green,blue )
Description: Set current mask color
Information: 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.

## GetMaskColor

Function GetMaskColor( red Var,green Var,blue Var )
Description: Get red, green and blue component of current mask color
Returns: Red, green and blue values in the range 0..255

## SetViewport

Function SetViewport( x,y,width,height )
Description: Set drawing viewport
Information: 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.

## GetViewport

Function GetViewport( x Var,y Var,width Var,height Var )
Description: Get dimensions of current Viewport.
Returns: The horizontal, vertical, width and height values of the current Viewport in the variables supplied.

## SetOrigin

Function SetOrigin( x#,y# )
Description: Set drawing origin
Information: The current Origin is an x,y coordinate added to all drawing x,y coordinates after any rotation or scaling.

## GetOrigin

Function GetOrigin( x# Var,y# Var )
Description: Get current origin position.
Returns: The horizontal and vertical position of the current origin.

## SetHandle

Function SetHandle( x#,y# )
Description: Set drawing handle
Information: The drawing handle is a 2D offset subtracted from the x,y location of all drawing commands except DrawImage as Images have their own unique handles.
Unlike SetOrigin the drawing handle is subtracted before rotation and scale are applied providing a 'local' origin.

## GetHandle

Function GetHandle( x# Var,y# Var )
Description: Get current drawing handle.
Returns: The horizontal and vertical position of the current drawing handle.

## SetRotation

Function SetRotation( rotation# )
Description: Set current rotation
Information: rotation is given in degrees and should be in the range 0 to 360.

## GetRotation

Function GetRotation#
Description: Get current Max2D rotation setting.
Returns: The rotation in degrees.

## SetScale

Function SetScale( scale_x#,scale_y# )
Description: Set current scale
Information: 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.

## GetScale

Function GetScale( scale_x# Var,scale_y# Var )
Description: Get current Max2D scale settings.
Returns: The current x and y scale values in the variables supplied.

## SetTransform

Function SetTransform( rotation#=0,scale_x#=1,scale_y#=1 )
Description: Set current rotation and scale
Information: SetTransform is a shortcut for setting both the rotation and scale parameters in Max2D with a single function call.

## LoadImageFont

Function LoadImageFont:TImageFont( url:Object,size,style=SMOOTHFONT )
Description: Load an image font
Returns: An image font object
Information: style can be a combination of BOLDFONT, ITALICFONT and SMOOTHFONT flags. Use the SMOOTHFONT flag for improved filtering if the font is to be rotated or scaled.

## SetImageFont

Function SetImageFont( font:TImageFont )
Description: Set current image font
Information: 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.
Use
to select the default, built-in font.

## GetImageFont

Function GetImageFont:TImageFont
Description: Get current image font.
Returns: The current image font.

## TextWidth

Function TextWidth( text$ )
Description: Get width of text
Returns: the width, in pixels, of text based on the current image font.
Information: This command is useful for calculating horizontal alignment of text when using the DrawText command.

## TextHeight

Function TextHeight( text$ )
Description: Get height of text
Returns: the height, in pixels, of text based on the current image font.
Information: This command is useful for calculating vertical alignment of text when using the DrawText command.

## LoadImage

Function LoadImage:TImage( url:Object,flags=-1 )
Description: Load an image
Returns: A new image object
Information: url can be either a string or an existing pixmap.
flags can be 0, -1 or any combination of:
| Flags value | Effect |
| MASKEDIMAGE | The image is masked with the current mask color. |
| FILTEREDIMAGE | The image is smoothed when scaled up to greater than its original size, when rotated, or when drawn at fractional pixel coordinates. |
| MIPMAPPEDIMAGE | The image is smoothed when scaled down to less than its original size. |
| DYNAMICIMAGE | The image can be modified using LockImage or GrabImage. |
Note MIPMAPPEDIMAGE images consume extra video memory, so this flag should only be used when really necessary.
If flags is -1, the auto image flags are used: See AutoImageFlags.
To combine flags, use the | (boolean OR) operator.

## LoadAnimImage

Function LoadAnimImage:TImage( url:Object,cell_width,cell_height,first_cell,cell_count,flags=-1 )
Description: Load a multi-frame image
Returns: An image object
Information: 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

Function SetImageHandle( image:TImage,x#,y# )
Description: Set an image's handle to an arbitrary point
Information: An image's handle is subtracted from the coordinates of DrawImage before rotation and scale are applied.

## AutoMidHandle

Function AutoMidHandle( enable )
Description: Enable or disable auto midhandle mode
Information: 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.
AutoMidHandle defaults to False after calling Graphics.

## AutoImageFlags

Function AutoImageFlags( flags )
Description: Set auto image flags
Information: The auto image flags are used by LoadImage and CreateImage when no image flags are specified. See LoadImage for a full list of valid image flags. AutoImageFlags defaults to MASKEDIMAGE | FILTEREDIMAGE.

## MidHandleImage

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

## ImageWidth

Function ImageWidth( image:TImage )
Description: Get width of an image
Returns: The width, in pixels, of image

## ImageHeight

Function ImageHeight( image:TImage )
Description: Get height of an image
Returns: The height, in pixels, of image

## CreateImage

Function CreateImage:TImage( width,height,frames=1,flags=-1 )
Description: Create an empty image
Returns: A new image object
Information: 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:

## LockImage

Function LockImage:TPixmap( image:TImage,frame=0,read_lock=True,write_lock=True )
Description: Lock an image for direct access
Returns: A pixmap representing the image contents
Information: 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

Function UnlockImage( image:TImage,frame=0 )
Description: Unlock an image
Information: Unlocks an image previously locked with LockImage.

## GrabImage

Function GrabImage( image:TImage,x,y,frame=0 )
Description: Grab an image from the back buffer
Information: Copies pixels from the back buffer to an image frame.
Only images created with the DYNAMICIMAGE flag can be grabbed.
Example:

## DrawPixmap

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

## GrabPixmap

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

## ImagesCollide

Function ImagesCollide(image1:TImage,x1,y1,frame1,image2:TImage,x2,y2,frame2)
Description: Tests if two images collide
Returns: True if any pixels of the two images specified at the given location overlap.
Information: ImagesCollide uses the current Rotation and Scale factors from the most previous call to SetScale and SetRotation to calculate at a pixel level if the two images collide.

## ImagesCollide2

Function ImagesCollide2(image1:TImage,x1,y1,frame1,rot1#,scalex1#,scaley1#,image2:TImage,x2,y2,frame2,rot2#,scalex2#,scaley2#)
Description: Tests if two images with arbitrary Rotation and Scales collide
Returns: True if any pixels of the two images specified at the given location overlap.
Information: ImagesCollide2 uses the specified Rotation and Scale paramteters to calculate at a pixel level if the two images collide (overlap).

## ResetCollisions

Function ResetCollisions(mask%=0)
Description: Clears collision layers specified by the value of mask, mask=0 for all layers.
Information: The BlitzMax 2D collision system manages 32 layers, the mask parameter can be a combination of the following values or the special value COLLISION_LAYER_ALL in order to perform collision operations on multiple layers.
Note: COLLISION_LAYER_32 is used by the ImagesCollide and ImagesCollide2 commands.
| Layer | Mask value |
| COLLISION_LAYER_ALL | 0 |
| COLLISION_LAYER_1 | $0001 |
| COLLISION_LAYER_2 | $0002 |
| COLLISION_LAYER_3 | $0004 |
| COLLISION_LAYER_4 | $0008 |
| COLLISION_LAYER_5 | $0010 |
| COLLISION_LAYER_6 | $0020 |
| COLLISION_LAYER_7 | $0040 |
| COLLISION_LAYER_8 | $0080 |
| COLLISION_LAYER_9 | $0100 |
| COLLISION_LAYER_10 | $0200 |
| COLLISION_LAYER_11 | $0400 |
| COLLISION_LAYER_12 | $0800 |
| COLLISION_LAYER_13 | $1000 |
| COLLISION_LAYER_14 | $2000 |
| COLLISION_LAYER_15 | $4000 |
| COLLISION_LAYER_16 | $8000 |

## CollideImage

Function CollideImage:Object(image:TImage,x,y,frame,collidemask%,writemask%,id:Object=Null)
Description: Pixel accurate collision testing between transformed Images.
Information: The collidemask specifies any layers to test for collision with.
The writemask specifies which if any collision layers the image is added to in its currently transformed state.
The id specifies an object to be returned to future CollideImage calls when collisions occur.
Example:

## CollideRect

Function CollideRect:Object(x,y,w,h,collidemask%,writemask%,id:Object=Null)
Description: Pixel accurate collision testing between image layers
Information: The collidemask specifies any layers to test for collision with.
The writemask specifies which if any collision layers the image is added to in its currently transformed state.
The id specifies an object to be returned to future CollideImage calls when collisions occur.