_COPYIMAGE

The _COPYIMAGE function creates an identical designated image in memory with a different negative LONG handle value.

Syntax

newhandle& = _COPYIMAGE[(imageHandle&[, mode%)]]

The LONG newhandle& value returned will be different than the source handle value supplied.
If imageHandle& parameter is omitted or zero is designated, the current software destination screen or image is copied.
If 1 is designated instead of an imageHandle&, it designates the last OpenGL hardware surface to copy.
Mode 32 can be used to convert 256 color images to 32 bit colors.
Mode 33 images are hardware accelerated in version 1.000 and up, and are created using _LOADIMAGE or _COPYIMAGE.

The function copies any image or screen handle to a new and unique negative LONG handle value.
Valid copy handles are less than -1. Invalid handles return -1 or 0 if it was never created.
Every attribute of the passed image or program screen is copied to a new handle value in memory.
32 bit screen surface backgrounds (black) have zero _ALPHA so that they are transparent when placed over other surfaces.

Use CLS or _DONTBLEND to make a new surface background _ALPHA 255 or opaque.

Images are not deallocated when the SUB or FUNCTION they are created in ends. Free them with _FREEIMAGE.
It is important to free discarded images with _FREEIMAGE to prevent PC memory allocation errors!
Do not try to free image handles currently being used as the active SCREEN. Change screen modes first.

Example: Restoring a Legacy SCREEN using the _COPYIMAGE return value.

SCREEN 13 CIRCLE (160, 100), 100, 40 DO: SLEEP: LOOP UNTIL INKEY$ <> "" 'backup screen before changing SCREEN mode oldmode& = _COPYIMAGE(0) 'the 0 value designates the current destination SCREEN s& = _NEWIMAGE(800, 600, 32) SCREEN s& LINE (100, 100)-(500, 500), _RGB(0, 255, 255), BF DO: SLEEP: LOOP UNTIL INKEY$ <> "" SCREEN oldmode& 'restore original screen IF s& < -1 THEN _FREEIMAGE s& END

Note: Only free valid handle values with _FREEIMAGE AFTER a new SCREEN mode is being used by the program.

Example 2: Program that copies desktop to a hardware image to form a 3D triangle (version 1.000 and up):

SCREEN _NEWIMAGE(640, 480, 32) my_hardware_handle = _COPYIMAGE(_SCREENIMAGE, 33) 'take a screenshot and use it as our texture _MAPTRIANGLE (0, 0)-(500, 0)-(250, 500), my_hardware_handle TO_ (-1, 0, -1)-(1, 0, -1)-(0, 5, -10), , _SMOOTH _DISPLAY DO: _LIMIT 30: LOOP UNTIL INKEY$ <> ""

Code courtesy of Galleon Example 2 PNG image