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 480x360, you would get an image of the full screen by calling this command with a width of 480 and a height of 360, but on an iPod this would produce an image of 480x360 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 480x360 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.

Definition

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

integer GetImage( x, y, width, height )

Parameters