COPYIMAGE

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

Syntax

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

Template:Parameters

• The LONG newhandle& value returned will be different than the source handle value supplied.
• If imageHandle& is designated being zero, 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.

Description

• 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.

Examples

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

See also

• _LOADIMAGE, _NEWIMAGE
• _PUTIMAGE, _MAPTRIANGLE
• _SOURCE, _DEST
• _FREEIMAGE
• _FILELIST$ (function) (Demo of _COPYIMAGE)
• _DISPLAYORDER
• Hardware images

---

Navigation: Main Page with Articles and Tutorials Keyword Reference - Alphabetical Keyword Reference - By usage Report a broken link