static DynamicSprite* DynamicSprite.CreateFromBackground
                      (optional int frame, optional int x, optional int y,
                       optional int width, optional int height)

The most basic use of this function is to supply no parameters, in which case the sprite will contain an exact copy of the current room background.

If you want, you can supply the frame only, in which case you will get a complete copy of that background frame number from the current room.

Optionally, you can specify a portion of the background to grab. You must either supply all or none of the x, y, width and height parameters; if you do supply them, this allows you to just get a small portion of the background image into the new sprite. All co-ordinates are in 320x200-resolution room co-ordinates.

Use the Graphic property of the DynamicSprite to interface with other commands and to use the new sprite in the game.

IMPORTANT: This command loads an extra sprite into memory which is not controlled by the normal AGS sprite cache and will not be automatically disposed of. Therefore, when you are finished with the image you MUST call Delete on it to free its memory.

IMPORTANT: If the DynamicSprite instance is released from memory (ie. there is no longer a DynamicSprite* variable pointing to it), then the sprite will also be removed from memory. Make sure that you keep a global variable pointer to the sprite until you are finished with it, and at that point call Delete.

Example:

DynamicSprite* sprite = DynamicSprite.CreateFromBackground(GetBackgroundFrame(), 130, 70, 60, 60);
DrawingSurface *surface = Room.GetDrawingSurfaceForBackground();
surface.DrawImage(0, 0, sprite.Graphic);
surface.Release();
sprite.Delete();

See Also: DynamicSprite.Delete