_COPYIMAGE - QB64Official/qb64 GitHub Wiki

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

Syntax

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

Parameter(s)

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

Example(s)

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.

Program that copies desktop to a hardware image to form a 3D triangle:


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$ <> ""