Difference between revisions of "COPYIMAGE"

From QB64 Wiki
Jump to navigation Jump to search
imported>Clippy
(Created page with ''''_COPYIMAGE''' Duplicates an image handle. ''Syntax:'' copyhandle& = _COPYIMAGE& [(handle AS LONG)] * Handle& copies any image handle to a new handle value. * Returns a c…')
 
(Removes references to qb64.net)
 
(41 intermediate revisions by 5 users not shown)
Line 1: Line 1:
'''_COPYIMAGE''' Duplicates an image handle.
+
{{DISPLAYTITLE:_COPYIMAGE}}
 +
The [[_COPYIMAGE]] function creates an identical designated image in memory with a different negative [[LONG]] handle value.
  
  
 +
{{PageSyntax}}
 +
: newhandle& = [[_COPYIMAGE]][({{Parameter|imageHandle&}}[, {{Parameter|mode%}})]]
  
  
''Syntax:'' copyhandle& = _COPYIMAGE& [(handle AS LONG)]
+
{{Parameters}}
 +
* 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|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]].
  
  
* Handle& copies any image handle to a new handle value.
+
{{PageDescription}}
* Returns a copy handle of - 1 if copy fails.
+
* The function copies any image or screen handle to a new and unique negative [[LONG]] handle value.
* Valid copy handles are less than -1.
+
* Valid copy handles are less than -1. Invalid handles return -1 or 0 if it was never created.
* If handle parameter is omitted, the current destination is copied.
+
* Every attribute of the passed image or program screen is copied to a new handle value in memory.
* Every attribute of the passed image is copied.
+
* '''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.'''
  
  
 +
{{PageExamples}}
 +
''Example:'' Restoring a Legacy SCREEN using the _COPYIMAGE return value.
 +
{{CodeStart}}'' ''
  
''Example:''
+
{{Cl|SCREEN}} 13
 +
{{Cl|CIRCLE}} (160, 100), 100, 40
 +
DO: {{Cl|SLEEP}}: {{Cl|LOOP}} {{Cl|UNTIL}} {{Cl|INKEY$}} <> ""
  
 +
'backup screen before changing {{Cl|SCREEN}} mode
 +
oldmode& = {{Cl|_COPYIMAGE}}(0)  'the 0 value designates the current destination {{Cl|SCREEN}}
  
 +
s& = {{Cl|_NEWIMAGE}}(800, 600, 32)
 +
{{Cl|SCREEN}} s&
 +
{{Cl|LINE}} (100, 100)-(500, 500), {{Cl|_RGB}}(0, 255, 255), BF
 +
DO: {{Cl|SLEEP}}: {{Cl|LOOP}} {{Cl|UNTIL}} {{Cl|INKEY$}} <> ""
  
''See also:'' [[_LOADIMAGE]], [[_NEWIMAGE]]
+
{{Cl|SCREEN}} oldmode&        'restore original screen
 +
{{Cl|IF...THEN|IF}} s& < -1 THEN {{Cl|_FREEIMAGE}} s&
 +
{{Cl|END}} '' ''
 +
{{CodeEnd}}
 +
: ''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:
 +
{{CodeStart}} '' ''
 +
{{Cl|SCREEN}} {{Cl|_NEWIMAGE}}(640, 480, 32)
 +
my_hardware_handle = {{Cl|_COPYIMAGE}}({{Cl|_SCREENIMAGE}}, 33) 'take a screenshot and use it as our texture
 +
{{Cl|_MAPTRIANGLE}} (0, 0)-(500, 0)-(250, 500), my_hardware_handle TO_
 +
(-1, 0, -1)-(1, 0, -1)-(0, 5, -10), , _SMOOTH
 +
{{Cl|_DISPLAY}}
 +
{{Cl|DO...LOOP|DO}}: {{Cl|_LIMIT}} 30: {{Cl|LOOP}} {{Cl|UNTIL}} {{Cl|INKEY$}} <> "" '' ''
 +
{{CodeEnd}}{{small|Code courtesy of Galleon}}
 +
 
 +
 
 +
{{PageSeeAlso}}
 +
* [[_LOADIMAGE]], [[_NEWIMAGE]]
 +
* [[_PUTIMAGE]], [[_MAPTRIANGLE]]
 +
* [[_SOURCE]], [[_DEST]]
 +
* [[_FREEIMAGE]]
 +
* [[_FILELIST$ (function)]] {{text|(Demo of _COPYIMAGE)}}
 +
* [[_DISPLAYORDER]]
 +
* [[Hardware images]]
 +
 
 +
 
 +
{{PageNavigation}}

Latest revision as of 15:44, 7 January 2021

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


Syntax

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


Parameters

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


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:

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



Navigation:
Go to Keyword Reference - Alphabetical
Go to Keyword Reference - By usage
Go to Main WIKI Page