# GetImage

## Description

Grabs a portion of the backbuffer and creates a new image from it. The position and size values must be in screen coordinates. Returns the ID of the new image, this must be deleted when you are done with it. To use this command effectively you must know how AGK draws to the back buffer. When Sync is called AGK updates the positions of all objects with Update, then draws them all to the back buffer with Render, without clearing it, then displays the back buffer to the screen with Swap. It then clears the back buffer and returns to your code, so if you were to call GetImage immediately after Sync you would get a blank image filled with the current clear color. Therefore if you want to grab an image of the current scene fully drawn you must call Render then GetImage then ClearScreen to clear the back buffer so Sync doesn't redraw everything over a fully drawn depth buffer. If you are already using Update, Render, and Swap yourself instead of Sync, then call GetImage between Render and Swap.
This also allows you to do things such as drawing lines to the back buffer, getting an image of the result and then clearing it so it doesn't effect what is displayed to the screen.
Calling GetImage is a slow command and it is not recommended that it be called every frame.
Note that the image produced by this command is not guaranteed to have the same width and height as those given to the command, this is because the image is created from a portion of the screen which has a different size on different devices. For example, with a virtual resolution of 480x320, you would get an image of the full screen by calling this command with a width of 480 and a height of 320, but on an iPhone this would produce an image of 480x320 pixels, whilst on an iPad it would be around 1024x768 pixels. This should not effect how you use the image as applying it to a sprite and setting the sprite size to the same 480x320 will make the sprite fill the screen in both cases. It simply means that on the iPad you have a higher quality image to play with.
This also applies to the line drawing commands, drawing a line from 0,0 to 100,100 and then getting an image from 0,0 to 100,100 will produce a diagonal line image on all devices, but high resolution screen devices will produce an image of higher quality containing more pixels. Use GetImageWidth and GetImageHeight if you need to know the actual size of the image produced in pixels.
When drawing transparent sprites and using GetImage on them AGK has to undo the blending of the sprite with the background color to retrieve an image that can be used again in future transparent sprites. As such you should not call SetClearColor unless you intend to call ClearScreen immediately after it.

## Definition

integer GetImage( x, y, width, height )

UINT agk::GetImage( float x, float y, float width, float height )

GetImage( imageID, x, y, width, height )

void agk::GetImage( UINT imageID, float x, float y, float width, float height )

## Parameters

- x - The x coordinate of the top left corner of the box to copy
- y - The y coordinate of the top left corner of the box to copy
- width - The width of the box to copy
- height - The height of the box to copy
- imageID - The image number that will contain the image captured