# BlitzMax/Modules/Graphics/Graphics

The graphics module provides the ability to create and 'flip' graphics objects.
A graphics object represents a rectangular area you can render to. However, the graphics module does not provide any commands for actual rendering - this is left to other modules such as max2D to implement.
The graphics module maintains 2 'current' objects - the current graphics driver and the currect graphics object. To change the current graphics driver, use SetGraphicsDriver. To change the current graphics object, use SetGraphics.
To create a graphics object, use either Graphics or CreateGraphics. The kind of graphics object created will depend upon the current graphics driver. For example, the following code:
Will create an OpenGL graphics object.
You can 'select' this object for rendering using:
One you have finished with a graphics object, use CloseGraphics to close it.
Graphics and CreateGraphics both accept the following parameters: width, height, depth, hertz and flags.
The width and height parameters specify the dimensions of the graphics, in pixels.
The depth parameter selects a pixel bit depth. This value can be 0, 16, 24 or 32 depending on the graphics modes available. A depth of 0 can be used to select 'windowed mode' graphics, while non-0 depths select 'fullscreen' graphics.
The hertz parameter selects a refresh rate, which refers to the number of times the screen refreshes per second. The refresh rates available depend on the graphics modes available, which differ from graphics card to graphics card. Note that creating graphics with an unsupported refresh rate will not fail - instead, a default refresh rate will be used.
The Graphics command can be used to achieve a fixed refresh rate. When using Flip to present such graphics, BlitzMax will guarantee the desired refresh rate is honored regardless of the available hardware's capabilities. This is achieved by using software timing techniques when necessary.
The flags parameter can be any combination of the following:
| Flags | Meaning |
| GRAPHICS_BACKBUFFER | Create graphics with a back buffer |
| GRAPHICS_ALPHABUFFER | Create graphics with an alpha buffer |
| GRAPHICS_DEPTHBUFFER | Create graphics with a depth buffer |
| GRAPHICS_STENCILBUFFER | Create graphics with a stencil buffer |
| GRAPHICS_ACCUMBUFFER | Create graphics with an accumulation buffer |
Flags can be combined with the | (or) operator. For example, GRAPHICS_BACKBUFFER|GRAPHICS_DEPTHBUFFER can be used to create graphics which has both a back buffer and a depth buffer.
Graphics created with the GRAPHICS_BACKBUFFER flag must be 'flipped' after you have finished rendering using Flip.

# Globals
## FlipHook

Global FlipHook=AllocHookId
Description: Flip Hook id
Information: Use this id with AddHook to register a function that is called every Flip.

# Functions
## SetGraphicsDriver

Function SetGraphicsDriver( driver:TGraphicsDriver,defaultFlags=GRAPHICS_BACKBUFFER )
Description: Set current graphics driver
Information: The current graphics driver determines what kind of graphics are created when you use the CreateGraphics or Graphics functions, as well as the graphics modes available.
The GLGraphicsDriver, GLMax2DDriver and D3D7Max2DDriver functions can all be used to obtain a graphics driver.
The defaultFlags parameter allows you to specify graphics flags that will be applied to any graphics created with CreateGraphics or Graphics.
Example:

## GraphicsModes

Function GraphicsModes:TGraphicsMode
Description: Get graphics modes available under the current graphics driver
Returns: An array of TGraphicsMode objects
Information: A TGraphicsMode object contains the following fields: width, height, depth and hertz
Example:

## CountGraphicsModes

Function CountGraphicsModes
Description: Get number of graphics modes available under the current graphics driver
Returns: Number of available Graphics modes
Information: Use GetGraphicsMode To obtain information about an individual Graphics mode

## GetGraphicsMode

Function GetGraphicsMode( index,width Var,height Var,depth Var,hertz Var )
Description: Get information about a graphics mode
Information: GetGraphicsMode returns information about a specific graphics mode. mode should be in the range 0 (inclusive) to the value returned by CountGraphicsModes (exclusive).

## GraphicsModeExists

Function GraphicsModeExists( width,height,depth=0,hertz=0 )
Description: Determine if a graphics mode exists
Returns: True if a matching graphics mode is found
Information: A value of 0 for any of width, height, depth or hertz will cause that parameter to be ignored.

## CreateGraphics

Function CreateGraphics:TGraphics( width,height,depth,hertz,flags )
Description: Create a graphics object
Returns: A graphics object
Information: CreateGraphics creates a graphics object. To use this object for rendering, you will first have to select it using SetGraphics.
The kind of graphics object returned depends upon the current graphics driver as set by SetGraphicsDriver.

## CloseGraphics

Function CloseGraphics( g:TGraphics )
Description: Close a graphics object
Information: Once closed, a graphics object can no longer be used.

## SetGraphics

Function SetGraphics( g:TGraphics )
Description: Set current graphics object
Information: SetGraphics will also change the current graphics driver if g uses a different driver than the current driver.

## GraphicsWidth

Function GraphicsWidth
Description: Get width of current graphics object
Returns: The width, in pixels, of the current graphics object
Information: The current graphics object can be changed using SetGraphics.

## GraphicsHeight

Function GraphicsHeight
Description: Get height of current graphics object
Returns: The height, in pixels, of the current graphics object
Information: The current graphics object can be changed using SetGraphics.

## GraphicsDepth

Function GraphicsDepth
Description: Get depth of current graphics object
Returns: The depth, in bits, of the current graphics object
Information: The current graphics object can be changed using SetGraphics.

## GraphicsHertz

Function GraphicsHertz
Description: Get refresh rate of current graphics object
Returns: The refresh rate, in frames per second, of the current graphics object
Information: The current graphics object can be changed using SetGraphics.

## GraphicsFlags

Function GraphicsFlags
Description: Get flags of current graphics object
Returns: The flags of the current graphics object
Information: The current graphics object can be changed using SetGraphics.

## Flip

Function Flip( sync=-1 )
Description: Flip current graphics object
Information: Flip swap the front and back buffers of the current graphics objects.
If sync is 0, then the flip occurs as soon as possible. If sync is 1, then the flip occurs on the next vertical blank.
If sync is -1 and the current graphics object was created with the Graphics command, then flips will occur at the graphics object's refresh rate regardless of whether or not the graphics hardware supports such a refresh rate.
If sync is -1 and the current graphics object was NOT created with the Graphics command, then the flip will occur on the next vertical blank.

## Graphics

Function Graphics:TGraphics( width,height,depth=0,hertz=60,flags=0 )
Description: Begin graphics
Returns: A graphics object
Information: Graphics is a convenience function that simplifies the process of creating a graphics object.
Once Graphics has executed, you can begin rendering immediately without any need for SetGraphics.
Graphics also enables polled input mode, providing a simple way to monitor the keyboard and mouse.

## EndGraphics

Function EndGraphics
Description: End graphics
Information: EndGraphics closes the graphics object returned by Graphics.